Payment

The payment object

Attribute

Type

Description

id

uuid

The unique identifier for the payment.

status

string

The payment status. open closed

fulfillment_status

string

The payment fulfillment status. unfulfilled partial fulfilled

amount

float

The total amount of the payment.

currency

string

Three-letter ISO-4217 code.

description

string

The title of the payment, visible to the owner and recipient.

image

Image

Default image if uploaded.

images

array

Array of all images if uploaded.

owner

Owner

The User which created the payment.

recipient

Participant

The payment recipient.

unclaimed_payment

UnclaimedPayment

A reference to an unclaimed payment, if the payment has yet to be claimed.

meta

string

A JSON object which can store meta data used by the client.

expires_at

time

If unclaimed, the payment needs to be claimed before this time.

created_at

time

The time when the payment was created.

updated_at

time

The time when the payment was updated.

Example

{
"id": "c5d8701e-05cf-4b15-52bf-1cf76c3d84f2",
"status": "open",
"fulfillment_status": "unfulfilled",
"amount": 20.00,
"currency": "EUR",
"description": "This is a payment description",
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/payments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/payments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/thumbnail/payments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"created_at": "2017-09-04T12:26:43.403883Z",
"updated_at": "2017-09-04T12:26:43.403883Z"
},
"owner": {
"id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"first_name": "John",
"last_name": "Dough",
"full_name": "John Dough",
"username": "jondough",
"country": "UK",
"timezone": "Europe/London",
"timezone_utc_offset": 0,
"verified": true,
"official": true,
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/users/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/users/moments/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"created_at": "2017-09-04T12:26:43.403883Z",
"updated_at": "2017-09-04T12:26:43.403883Z"
},
},
"recipient": {
"id": "9c2da03a-5526-457d-b7a4-0e250c46b433",
"user_id": "baec7eb0-bb93-4ff4-94b0-feb27ad6c2e6",
"transaction_id": "0baa166e-3130-4420-b30f-99a25829fd99",
"status": "pending",
"amount": 20,
"currency": "EUR",
"messages": null,
"username": "",
"created_at": "2018-08-13T11:52:07.810308Z",
"updated_at": "2018-08-13T11:52:07.810308Z",
},
"unclaimed_payment": {
"id": "c4100f1d-5640-42d2-bf38-eea5bb615d04",
"funding_source_id": "d6fec003-9172-4acb-8a4f-284452aa1ebf",
"transaction_id": "0baa166e-3130-4420-b30f-99a25829fd99",
"processed": false,
"error": false,
"error_message": "",
"expires_at": "2017-09-14T12:26:43.35539Z",
},
"meta": "",
"expires_at": "2017-09-14T12:26:43.35539Z",
"created_at": "2017-09-04T12:26:43.35539Z",
"updated_at": "2017-09-04T12:26:43.48788Z"
}

The unclaimed payment object

Attribute

Type

Description

id

uuid

The unique identifier for the unclaimed payment.

funding_source_id

uuid

The unique identifier for the withdrawal funding source.

transaction_id

uuid

The unique identifier for the transaction of the parent payment.

processed

bool

Indicates whether or not the payment has been claimed and processed.

error

bool

Indicates whether or not there was an error processing the unclaimed payment.

error_message

string

Error details, in case of an error.

expires_at

time

The unclaimed payment needs to be claimed before this time.

created_at

time

The time when the unclaimed payment was created.

updated_at

time

The time when the unclaimed payment was updated.

Example

{
"id": "c4100f1d-5640-42d2-bf38-eea5bb615d04",
"funding_source_id": "d6fec003-9172-4acb-8a4f-284452aa1ebf",
"transaction_id": "0baa166e-3130-4420-b30f-99a25829fd99",
"processed": false,
"error": false,
"error_message": "",
"expires_at": "2017-09-14T12:26:43.35539Z",
"created_at": "2017-09-04T12:26:43.35539Z",
"updated_at": "2017-09-04T12:26:43.48788Z"
}

Get a list of payments

Get a list of all payments created by the user and payments where the user is the recipient. This can be specified by using the owner filter.

Request
Response
Request

GET /v1/payments

Query Parameters

Name

Type

Description

page

int

Item pagination.

limit

int

Number of items to return per page.

sort

string

Sort the results by created_at, updated_at.

filter

string

Filter the results.

Filtering

Attribute

Type

Operators

Values

owner

boolean

eq

true, false

status

string

eq, in

open, closed, all default: all

Response

200 OK

Returns a payment object.

Get a payment

Get a single payment by ID. Transactions are not accessible from this endpoint (see Transactions).

Request
Response
Request

GET /v1/payments/{id}

Response

200 OK

Returns a payment object.

Create a payment

Create a new payment and send money. Recipient can be based on a user ID or phone number, in which case an optional name can also be sent. Payment source and PIN is required for payments.

Request
Response
Request

POST /v1/payments

Attribute

Type

Description

currency

string

Three-letter ISO-4217 code. Must be a supported currency. required

description

string

The payment message.

recipient

Participant

The recipient of the funds. required

image

Image

An optional payment image.

image_ids

array

A list of image identifiers, for uploading multiple images.

funding_source_id

uuid

The unique identifier for the funding source which will be withdrawn from. required

destination_funding_source_id

uuid

The unique identifier for the receiving funding source if a transfer is being made between two funding sources belonging to the same user.

pin

string

The current user's PIN. required

{
"currency": "EUR",
"description": "This is a payment description",
"recipient": {
"amount": 20.0,
"user_id": "3fb6e878-58d6-47f6-ba3c-a5089d6e039a"
},
"image": {
"url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
},
"funding_source_id": "f36525d5-39f4-48a9-a547-1887cc69b5cf",
"pin": "1234"
}
Response

201 Created

Returns a payment object.