Create a payment request and deliver it to the recipient. The recipient then has a designated amount of time to respond (90 seconds by default), either by paying or rejecting. If no action is taken, the payment request expires and the recipient can no longer pay.
When the payment request status has changed, a notification callback is posted to the URL defined in notify_url with the payment request data. If a notify_url is not defined, no notification callback is posted.
POST /v1/requests
Key | Type | Description |
amount | float | The amount being requested. |
currency | string | Three-letter ISO-4217 code. Must be a supported currency. |
description | string | Message to payer. |
image_url | string | URL to an image which the payer will see. |
order | string | Custom value which will be returned in the notification callback data. The payer never sees this value. |
recipient | string | A recipient's username or phone number. Phone number can include the country code (not required). Adding multiple recipients is currently not supported. |
terminal | int | Custom value which will be returned in the notification callback data. The payer never sees this value. |
expires_in | int | Expiry time in seconds. Minimum 10 seconds, maximum 7 days. Default value is 90 seconds. |
notify_url | string | If this URL is defined you will receive a notification callback from the API with the payment data (and a signature) when the payment request status changes. |
{"amount": 10.99,"currency": "USD","description": "T-shirt","image_url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg","order": "abc123","recipient": "+14155551212","terminal": 1,"expires_in": 90,"notify_url": "https://example.com/notification"}
200 OK
Key | Type | Description |
success | boolean | Is true if the payment request was delivered. |
id | uuid | The unique identifier for the payment request. |
created | int | The date and time when the payment request was created. UTC (GMT +0) UNIX timestamp. |
error | Error | Error data, if the success value is false. |
{"success": true,"id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc","created": 1458748385}
{"success": false,"error": {"code": "200","key": "recipient_not_found","message": "Recipient not found"}}
Get a single payment request.
GET /v1/requests/{id}
200 OK
Key | Type | Description |
id | uuid | The unique identifier for the payment request. |
transaction_id | uuid | The payment's transaction ID. Only issued if the request has been paid. Not issued if the request is unpaid, rejected or expired. |
amount | float | The amount requested to be paid. |
currency | string | Three-letter ISO-4217 code. |
description | string | Message sent to the payer. |
image_url | string | URL to an image which the payer sees. |
status | string | The payment request status. Note: Rejected can either mean that the payer declined or the payment request expired.
|
order | string | Same value as posted when the payment request was created. |
created | int | The date and time when the payment request was created. UTC (GMT +0) UNIX timestamp. |
updated | int | The date and time when the payment request was last updated. UTC (GMT +0) UNIX timestamp. |
expires | int | The date and time when the payment request expires. UTC (GMT +0) UNIX timestamp. |
{"id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc","transaction_id": "a917be59-f35a-478f-a5d9-19bf467972ad","amount": 10.99,"currency": "USD","description": "T-shirt","image_url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg","status": "paid","order": "abc123","created": 1458748385,"updated": 1458748422,"expires": 1458748475}
Get a single payment request's status and expiration timestamp. This may be more convenient than getting the entire payment request object if you only need to know the status.
GET /v1/requests/{id}/status
200 OK
Key | Type | Description |
id | uuid | The unique identifier for the payment request. |
status | string | The payment request status. Note: Rejected can either mean that the payer declined or the payment request expired.
|
expires | int | The date and time when the payment request expires. UTC (GMT +0) UNIX timestamp. |
{"id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc","status": "pending","expires": 1458748475}