Managing invoices

This page will give examples on how to:

Send Invoice as Quote

If you send the invoice with the status Quote, the customer will be able to view the invoice, but they will not be able to pay it. To give the customer the permission to pay the invoice, you must mark-as-sent. The API endpoint for sending an invoice is as follows:

POST /api/v2/invoices/:key:/send

Request

curl -X POST https://secure.usaepay.com/api/v2/invoices/fskjtxydkx3grpz3/send
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"

This cURL request is an example of a request to send an invoice quote to a customer.

Response

{
    "status": "success"
}

This is the sample response object sent back from the server.

Parameters

Request

The request parameters are listed below

Parameter Required Type Description
key Required string Invoice identifier generated by gateway.

Response

The response parameters are listed below

Parameter Description
status If invoice is sent then status will be returned as success. If invoice is not sent, an error will be returned instead.

Send and Mark as Sent

If you send the invoice with the status Quote, the customer will be able to view the invoice, but they will not be able to pay it. To give the customer the permission to pay the invoice, you must mark-as-sent. The API endpoint for sending an invoice and marking as sent is as follows: (it is the same endpoint as above)

POST /api/v2/invoices/:key:/send

Request

curl -X POST https://secure.usaepay.com/api/v2/invoices/fskjtxydkx3grpz3/send
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
    '{
    "mark_as_sent": true
   }'

This cURL request is an example of a request to send an invoice marked as sent.

Response

{
    "status": "success"
}

This is the sample response object sent back from the server.

Parameters

Request

Parameter Required Type Description
key Required string Invoice identifier generated by gateway.
mark_as_sent Required string Setting to true will finalize the invoice. Denotes the invoice has been marked as sent and emailed to the customer. Customer can now pay the invoice.

Response

Parameter Description
status If invoice is sent then status will be returned as success. If invoice is not sent, an error will be returned instead.

Cancel

The API endpoint for sending an invoice and marking as sent is as follows:

POST /api/v2/invoices/:key:/cancel

Please Note: Once an invoice has been paid, it cannot be cancelled.**

Request

curl -X POST https://secure.usaepay.com/api/v2/invoices/fskjtxydkx3grpz3/cancel
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"

This cURL request is an example of a request to cancel an invoice.

Response

{
    "status": "success"
}

This is the sample response object sent back from the server.

Parameters

Request

Parameter Required Type Description
key Required string Invoice identifier generated by gateway.

Response

Parameter Description
status If invoice is cancelled then status will be returned as success. If invoice is not cancelled, an error will be returned instead.

Mark as Paid

If you a customer has paid their invoice, but did not pay through the invoice link you sent out, you may want to keep the invoice record, but mark the invoice as paid. The API endpoint for marking an invoice as paid is as follows:

POST /api/v2/transactions

You can mark as paid by external ACH, external credit card, and cash. Please Note: Once an invoice has been paid, it cannot be cancelled.

Mark as Paid: ACH

Request

curl -X POST https://secure.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "external:check:sale",
    "invoice_key": "7skjthm4k0wbmsp3",
    "invoice": "123",
    "check": {
        "accountholder": "John doe",
        "number": "10001"
    },
    "amount_detail": {
        "subtotal": "2.00",
        "tax": "1.40",
        "nontaxable": "N",
        "tip": "0.00",
        "shipping": "12.00",
        "discount": "10.00"
    },
    "amount": "5.40"
    }

This cURL request is an example of a request to mark an invoice as paid by external ACH payment.

Response

{
    "type": "transaction",
    "key": "2nfk7zfn9vgf33y",
    "refnum": "1629344134",
    "is_duplicate": "N",
    "result_code": "A",
    "result": "Approved",
    "authcode": "",
    "invoice": "123"
}

This is the sample response object sent back from the server.

Mark as Paid: Credit Card

Request

curl -X POST https://secure.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "external:cc:sale",
    "invoice_key": "dskjtxy13b8fq4c3",
    "invoice": "123",
    "amount_detail": {
        "subtotal": "2.00",
        "tax": "1.40",
        "nontaxable": "N",
        "tip": "0.00",
        "shipping": "12.00",
        "discount": "10.00"
    },
    "amount": "5.40",
    "creditcard": {
        "cardholder": "Ava Rodriguez"
    }
    }'

This cURL request is an example of a request to mark an invoice as paid by external credit card payment.

Response

{
    "type": "transaction",
    "key": "1nfj1h3435xttjz",
    "refnum": "1629344133",
    "is_duplicate": "N",
    "result_code": "A",
    "result": "Approved",
    "authcode": "",
    "invoice": "123"
}

This is the sample response object sent back from the server.

Mark as Paid: Cash

Request

curl -X POST https://secure.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
  "command": "cash",
  "invoice_key": "jskjtq9sq12btrx3",
  "invoice": "123",
  "amount_detail": {
      "subtotal": "2.00",
      "tax": "1.40",
      "nontaxable": "N",
      "tip": "0.00",
      "shipping": "12.00",
      "discount": "10.00"
  },
  "amount": "5.40"
  }'

This cURL request is an example of a request to mark an invoice as paid with cash.

Response

{
    "type": "transaction",
    "key": "2nfk7zfn9vgf33y",
    "refnum": "1629344134",
    "is_duplicate": "N",
    "result_code": "A",
    "result": "Approved",
    "authcode": "",
    "invoice": "123"
}

This is the sample response object sent back from the server.

Mark as Paid Parameters

Request

The request parameters are listed below

Parameter Required Type Description
command Required string Denotes which tender was used for external sale. Possible values: external:check:sale- ACH, external:cc:sale- Credit Card, and cash- cash.
invoice_key Required string Invoice identifier generated by gateway.
invoice string Invoice identifier generated by merchant. Character limit: 25.
check Required Only for ACH check Check object. Only accepted fields are: number and accountholder.
creditcard Required Only for Credit Card creditcard Credit card object. Only accepted fields is: cardholder.
amount_detail amount_detail Amount detail object.
amount Required double Total amount. amount = lineitem totals - (discount + shipping + tax)

Response

Below are the response parameters. Please note: if the parameter was defined in the request parameters above, they are not included in the table below.

Parameter Type Description
type string 'transaction'- denotes this object is a transaction.
key string Transaction identifier generated by gateway.
refnum string Transaction identifier generated by gateway.
is_duplicate boolean Denotes if this transaction is a duplicate. Possible Values: Y- true or N- false.
result_code string Result code ('A' = Approved, 'P' = Partial Approval, 'D' = Declined, 'E' = Error, or 'V' = Verification Required)
result string Long version of above result_code ('Approved', etc)
authcode string Authorization code (no authorization codes are provided for external transactions).

Errors

Code Message Description
49 Merchant ID Mismatch for record locator key Invoice does not belong to this merchant
51 Failed to create 'invoice' due to invalid data Verify all required fields are included and valid.
3003 Unable To delete Invoice. Please Contact Support. Unable to delete one or more Invoices due to current status.
3006 Unable to update Invoice due to current status Cannot update invoice with cancelled status.
3007 Unable to delete Invoice due to current status Cannot delete invoice due to current status.
3008 Unable to delete Invoice due to current status Invoice has already been cancelled or cannot cancel invoice that has not been sent.
3009 Unable to refund Invoice due to current status Cannot refund an invoice that has not been paid.
19001 The field '[field]' is required. Field is invalid.
21003 Access Denied You do not have the permission to perform this action.
99999 Invoice Not Found The invoice key is incorrect.

Change Log

Date Change
2018-02-27 Added page.

Click here for the full REST API change log.