# 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.

![Image showing the results of a payment request on a mobile phone. ](https://files.readme.io/b2a40c2-payments-request2x.png "payments-request@2x.png")

|                                  |                       |
| :------------------------------- | :-------------------- |
| *(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](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payment-requests).

```json
POST <URL>payments/v1/payment-requests
```

## Sample payload request

```json 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

```json 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:

```json
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](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payment-requests) 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](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payments) .

![Image showing the Confirm payment request on a mobile phone. ](https://files.readme.io/95c7614-payments-request-confirm2x.png "payments-request-confirm@2x.png")

## Sample payload request

```json 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](https://developers.pismo.io/pismo-docs/reference/get-payments-v1-payment-requests).

```json
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`.

```json List all payments response example
[
  {
    "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](https://developers.pismo.io/pismo-docs/docs/payments)\
[Guides / Make a transfer](https://developers.pismo.io/pismo-docs/docs/make-transfer)\
[API reference / Create payment request](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payment-requests)\
[API reference / Transfer funds](https://developers.pismo.io/pismo-docs/reference/post-payments-v1-payments)\
[API reference / List payment requests](https://developers.pismo.io/pismo-docs/reference/get-payments-v1-payment-requests)