Payment requests
The Pismo platform enables you to give users an easy way to send payment requests to their peers, such as splitting the barbecue bill or reminding a friend about a group birthday present. Payment requests can be set to expire, contain personalized messages, and more.
Send a payment request
A payment request is essentially a step before a payment transfer. When sending a payment request, the request must contain the required destination account id and the amount fields and can contain other optional fields such as expiration date or metadata. In case of success, the response returns a token in the field code. You can use this token to further process the transfer. The payment request can be accepted (paid) or declined by the receiver, or even canceled by the sender.
| (A) sender | (D) amount |
| (B) account ID of the receiver | (E) expiration date |
| (C) currency | (F) metadata |
API reference
You can send a payment request by using the following endpoint. For more information, go to Create payment request.
POST <URL>payments/v1/payment-requests
Sample payload request
{
"amount": 25.50,
"from":{
"currency": "USD",
"account":{
"id": 8795
}
},
"to":{
"currency": "USD",
"account":{
"id": 6789
}
},
"expiration": "2020-02-01T21:22:12.800Z",
"metadata":{
"message": "David's birthday present"
}
}
Sample response
{
"type": "TOKEN",
"code": "c8y4865-7654876-zdfi76-23436k"
}
Confirm a payment request
If you want to confirm a payment request, you need to create a new payment using the following endpoint:
POST <URL>payments/v1/payments
In the request, provide the attribute called token with the value generated while creating the original payment request. This is the value returned in the code field of the Create payment request endpoint. If the provided token does not exist or if it is expired, your request returns an error 400. For more information on creating a payment, go to Transfer funds .
Sample payload request
{
"descriptor": "PAYMENT REQUEST ACCEPT",
"token": "c8y4865-7654876-zdfi76-23436k",
"from": [
{
"amount": 25.50,
"currency": "USD",
"account": {
"id": 8795
}
}
],
"to": [
{
"currency": "USD",
"account": {
"id": 6789
}
}
],
"metadata": [
{
"source": "account balance",
"message": "David's birthday present"
}
]
}
List all payment requests
You can get a list of all payment requests sent from or to a given account by using the following endpoint. For more information, go to List payment requests.
GET <URL>payments/v1/payments-requests
Fill in exclusively the to or from query parameter with a valid account ID, according to what kind of payment requests you want to list. For example, payments/v1/payments-requests?to=6789.
[
{
"amount": 25.50,
"to": 6789,
"expiration": "2020-02-01T21:22:12.800Z",
"location": {
"lat": 12.2,
"lng": -12.2
},
"status": "PAID",
"id": "c8y4865-7654876-zdfi76-23436k",
"creation_date": "2022-01-07T00:04:10.713Z",
"metadata": {
"source": "account balance",
"message": "David's birthday present"
}
},
{
"amount": 10.0,
"to": 6789,
"expiration": "2022-01-06T10:39:00.000Z",
"location": {
"lat": 12.2,
"lng": -12.2
},
"status": "EXPIRED",
"id": "f197146f-463f-4cdf-96ac-50a3133801a0",
"creation_date": "2022-01-02T00:04:20.649Z",
"metadata": {
"my-custom-key": "my-custom-value"
}
},
{
"amount": 50.0,
"to": 6789,
"expiration": "2022-02-25T10:39:00.000Z",
"location": {
"lat": 12.2,
"lng": -12.2
},
"status": "PENDING",
"id": "fa60cfc3-a5d5-4af1-a193-e20ca6446e5b",
"creation_date": "2022-01-07T00:05:12.950Z",
"metadata": {
"some-key": "some-value"
}
}
]
Related pages
Guides / Payments and transfers
Guides / Make a transfer
API reference / Create payment request
API reference / Transfer funds
API reference / List payment requests
Updated 9 months ago