Payment Requests

Create a payment request
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.
Request
Response
Request
POST /v1/requests
Key
Type
Description
amount
float
The amount being requested. required
currency
string
Three-letter ISO-4217 code. Must be a supported currency. required
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"
}
Response
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.
Example - Success
{
    "success": true,
    "id": "3e6975e8-77cb-48b7-7722-3dfe47677bbc",
    "created": 1458748385
}
Example - Error
{
    "success": false,
    "error": {
        "code": "200",
        "key": "recipient_not_found",
        "message": "Recipient not found"
    }
}
Get payment request
Get a single payment request.
Request
Response
Request
GET /v1/requests/{id}
Response
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.
pending
paid
rejected
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 payment request status
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.
Request
Response
Request
GET /v1/requests/{id}/status
Response
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.
pending
paid
rejected
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
}

Errors

Notification Callback

Last updated 1 year ago

Key	Type	Description
amount	float	The amount being requested. `required`
currency	string	Three-letter ISO-4217 code. Must be a supported currency. `required`
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.

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.