Managing invoices

This page will give examples on how to:

• Send invoice as a quote.
• Send invoice and mark as sent.
• Cancel invoice.
• Mark invoice as paid.
  • ACH
  • Credit Card
  • Cash

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.