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.
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.newtekgateway.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.newtekgateway.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.newtekgateway.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.newtekgateway.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.newtekgateway.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.newtekgateway.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. |