Requests

A request referers to a payment request.

The request object

Attribute

Type

Description

id

uuid

The unique identifier for the request.

status

string

The request status. open closed

fulfillment_status

string

The request fulfillment status. unfulfilled partial fulfilled

amount

float

The total amount of the request.

amount_paid

float

The amount that has already been paid.

currency

string

Three-letter ISO-4217 code.

description

string

The title of the request, visible to the owner and participants.

image

Image

Default image if uploaded.

images

array

Array of all images if uploaded.

owner

Owner

The User which created the request.

participant

Participant

The current user's participant object, if the current user is in the list of participants.

participation

Participation

Participation information for the request.

meta

string

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

created_at

time

The time when the request was created.

updated_at

time

The time when the request was updated.

Example

{
"id": "c5d8701e-05cf-4b15-52bf-1cf76c3d84f2",
"status": "open",
"fulfillment_status": "partial",
"amount": 20.00,
"amount_paid": 10.00,
"currency": "EUR",
"description": "Payment request",
"image": {
"id": "75cc21be-fe47-4702-74bc-07b84beed5fb",
"url": "https://{imagehost}/ui/requests/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"full_screen_url": "https://{imagehost}/full/requests/ad2636c3-82fe-4c45-af2d-d6324b2e618f.jpg",
"thumbnail_url": "https://{imagehost}/thumbnail/requests/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"
},
"relationships": [
{
"id": "4ec5c820-520d-4668-ba84-0d7bdee23af5",
"type": "contact",
"created_at": "2017-04-19T14:35:09.308904Z",
"updated_at": "2017-04-19T14:35:09.308904Z"
}
]
},
"participant": {
"id": "a0bcfb20-99fd-465d-6e23-2e19e8952420",
"user_id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"transaction_id": "875ef796-88a1-4c7f-8755-d4cb066b9a3e",
"status": "paid",
"amount": 10.00,
"currency": "EUR",
"full_name": "Arnar Participant",
"username": "arnarpart",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
},
"participation": {
"count": {
"invited": 0,
"paid": 2,
"pending": 2,
"rejected": 1,
"total": 5
},
},
"meta": "",
"created_at": "2017-09-04T12:26:43.35539Z",
"updated_at": "2017-09-04T12:26:43.48788Z"
}

Get a list of requests

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

Request
Response
Request

GET /v1/requests

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 list of request objects.

Get a request

Get a single request by ID.

Request
Response
Request

GET /v1/requests/{id}

Response

200 OK

Returns a request object.

Create a request

Create a new payment request.

Request
Response
Request

POST /v1/requests

Attribute

Type

Description

amount

float

The amount being paid. required

currency

string

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

description

string

The title of the request, visible to the owner and participants.

funding_source_id

uuid

The unique identifier of the funding source receiving payment. required

image

Image

An optional request image.

image_ids

array

A list of image identifiers, for uploading multiple images.

only_owner_sees_participants

boolean

Whether the owner is the only one who can see the list of participants. Default: false.

participants

array

A list of participants in the request. required

{
"amount": 20.0,
"currency": "EUR",
"description": "Payment request",
"funding_source_id": "d4097613-3b63-4dbb-befe-2211b9dc821a",
"image": {
"url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
},
"only_owner_sees_participants": false,
"participants": [
{
"user_id": "3fb6e878-58d6-47f6-ba3c-a5089d6e039a",
"amount": 10.0
},
{
"phone": "+44 111 2222 3333",
"name": "John Dough",
"amount": 10.0
}
]
}
Response

201 Created

Returns a request object.

Update a request

Update an existing request. Can only update description and image.

Request
Response
Request

PUT /v1/requests/{id}

Attribute

Type

Description

description

string

The title of the request, visible to the owner and participants.

image

Image

An optional request image.

{
"description": "My Updated Description",
"image": {
"url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
},
"only_owner_sees_participants": true
}
Response

200 OK

Returns a request object.

Delete a request

Delete an existing request. Can only be performed if none of the participants have responded.

Request
Response
Request

DELETE /v1/requests/{id}

Response

200 OK

Get request participants

Get a list of participants in a payment request.

Request
Response
Request

GET /v1/requests/{id}/participants

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

status

string

eq

cancelled, paid, pending, rejected, settled

Response

200 OK

Returns a list of participant objects.

[
{
"id": "a0bcfb20-99fd-465d-6e23-2e19e8952420",
"user_id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"transaction_id": "875ef796-88a1-4c7f-8755-d4cb066b9a3e",
"status": "paid",
"amount": 20.00,
"currency": "EUR",
"full_name": "Arnar Participant",
"username": "arnarpart",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
}
]

Remind a participant to pay

Send a reminder to a request participant in form of a push notification. Note: There is a limit to how many times a participant can be reminded. Exceeding this limit will return in an error message.

Request
Response
Request

POST /v1/requests/{id}/participants/{id}/remind

Response

200 OK

Settle a participant

Mark a participant as paid.

Request
Response
Request

POST /v1/requests/{id}/participants/{id}/settle

Response

200 OK

Cancel a participant

Cancel the request for a participant.

Request
Response
Request

POST /v1/requests/{id}/participants/{id}/cancel

Response

200 OK

Pay a request

Pay an existing request as a participant. Funding source and PIN is required for payments.

Request
Response
Request

POST /v1/requests/{id}/participants/{id}/pay

Attribute

Type

Description

funding_source_id

uuid

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

pin

string

The current user's PIN. required

{
"funding_source_id": "d4097613-3b63-4dbb-befe-2211b9dc821a",
"pin": "1234"
}
Response

200 OK

{
"id": "a0bcfb20-99fd-465d-6e23-2e19e8952420",
"user_id": "add5c52a-0c57-4d5c-7525-db14566f2f1a",
"transaction_id": "875ef796-88a1-4c7f-8755-d4cb066b9a3e",
"status": "paid",
"amount": 20.00,
"currency": "EUR",
"full_name": "John Dough",
"username": "jondough",
"created_at": "2017-09-04T12:26:43.398646Z",
"updated_at": "2017-09-04T12:26:43.398646Z"
}

Reject a request

Reject an existing request as a participant.

Request
Response
Request

POST /v1/requests/{id}/reject

Response

200 OK

Get a receipt

Get a payment receipt as a participant. The request must be paid, otherwise no receipt will be returned.

Request
Response
Request

GET /v1/requests/{id}/receipt

Response

200 OK

Returns a receipt object.

Get a receipt for a participant

Get a payment receipt for a specific participant in the request. The participant must have paid, otherwise no receipt will be returned. The request owner will not see the payment method.

Request
Response
Request

GET /v1/requests/{id}/participants/{id}/receipt

Response

200 OK

Returns a receipt object.