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
}