> For the complete documentation index, see [llms.txt](https://docs.papayaglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papayaglobal.com/api-reference/payment-management/update-payment-instructions.md).

# Update Payment Instructions

The API updates existing payment instructions (or creates them with an explicit ID).

<mark style="color:orange;">**`PUT`**</mark> /payments/payments/{id}

**Body parameters - Request**

| Name                 | Location | Type    | Format / Values | Description                                                                                                                                                                                                                                                                            | Required               |
| -------------------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| id                   | Url Path | string  |                 | A unique id for this payment (if none provided, an id will be assigned). Using an existing payment id will update the pending payment                                                                                                                                                  |                        |
| description          | body     | string  |                 | The remittence info to send as part of the payment                                                                                                                                                                                                                                     |                        |
| purpose              | body     | string  | /^(\[A-Z]{4})$/ | the purpose of the payment as a 4 letter iso-20022 code. see: <[![](https://www.iso20022.org/themes/custom/iso20022_theme/images/favicon/favicon-32x32.png)External code sets \| ISO20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets) | No, defaults to `SALA` |
| source               | body     | object  |                 |                                                                                                                                                                                                                                                                                        | Yes                    |
| source.type          | body     | string  | group           | type of source (must be group)                                                                                                                                                                                                                                                         |                        |
| source.id            | body     | string  |                 |                                                                                                                                                                                                                                                                                        | Yes                    |
| target               | body     | object  |                 |                                                                                                                                                                                                                                                                                        | Yes                    |
| target.type          | body     | string  | contact         |                                                                                                                                                                                                                                                                                        |                        |
| target.id            | body     | string  |                 | The id of the target entity (beneficiary)                                                                                                                                                                                                                                              | Yes                    |
| approved             | body     | boolean |                 | Set to true to mark the payment as approved and ready to be executed                                                                                                                                                                                                                   |                        |
| amount               | body     | object  |                 | Specifies the amount of the payment                                                                                                                                                                                                                                                    | Yes                    |
| amount.type          | body     | string  | LAND, SEND      | Does the amount refer to the amount credited (LAND), or the amount debited (SEND)                                                                                                                                                                                                      |                        |
| amount.amount        | body     | number  |                 | The amount (up to 3 decimal points)                                                                                                                                                                                                                                                    | Yes                    |
| amount.currency      | body     | string  | /^\[A-Z]{3}$/   | If the amount currency is different than the sender (for SEND) or target (for LAND), specify the 3 letter ISO currency code of the payment                                                                                                                                             |                        |
| execution            | body     | object  |                 | specifies info for the executing date                                                                                                                                                                                                                                                  | Yes                    |
| execution.type       | body     | string  | SEND, LAND      | Does the date refer to the date the funds should arrive (LAND) or the date the funds should be sent (SEND), defaults to amount.type (future support)                                                                                                                                   |                        |
| execution.date       | body     | string  | date-time       | The date this payment should be sent on (for SEND payments) or the date this payment should arrive by (for LAND payments)                                                                                                                                                              | Yes                    |
| execution.margin     | body     | integer |                 | number of hours before execution date, this payment may be sent if funds exist                                                                                                                                                                                                         |                        |
| final                | body     | object  |                 | Properties describing the finalization of this payment details                                                                                                                                                                                                                         |                        |
| final.is\_final      | body     | boolean |                 | is the amount final                                                                                                                                                                                                                                                                    |                        |
| final.expected       | body     | string  | date-time       | If the amount is not final yet, when is the final amount expected                                                                                                                                                                                                                      |                        |
| attachments          | body     | array   | object          | List of files to attach to the payment                                                                                                                                                                                                                                                 |                        |
| attachments\[].id    | body     | string  |                 | a unique id to give the attachment                                                                                                                                                                                                                                                     |                        |
| attachments\[].title | body     | string  |                 | A title to give the attachment                                                                                                                                                                                                                                                         |                        |
| attachments\[].url   | body     | string  |                 | a url link to the attachment                                                                                                                                                                                                                                                           | Yes                    |
| user\_tags           | body     | object  |                 | A set of key/value pairs to tag the payment with                                                                                                                                                                                                                                       |                        |

**Body Parameters -** **Response**

| Name                  | Type                       | Format / Values                                                       | Description                                                                                                                                                                                                                                                                            |
| --------------------- | -------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount                | object                     |                                                                       | Specifies the amount of the payment                                                                                                                                                                                                                                                    |
| amount.type           | string                     | LAND, SEND                                                            | Does the amount refer to the amount credited (LAND), or the amount debited (SEND)                                                                                                                                                                                                      |
| amount.amount         | number                     |                                                                       | The amount (up to 3 decimal points)                                                                                                                                                                                                                                                    |
| amount.currency       | string                     | /^\[A-Z]{3}$/                                                         | If the amount currency is different than the sender (for SEND) or target (for LAND), specify the 3 letter ISO currency code of the payment                                                                                                                                             |
| approved              | boolean                    |                                                                       | Has this payment been approved and ready for execution                                                                                                                                                                                                                                 |
| attachments           | array                      | object                                                                | List of files to attach to the payment                                                                                                                                                                                                                                                 |
| attachments\[]        | object                     |                                                                       |                                                                                                                                                                                                                                                                                        |
| attachments\[].id     | string                     |                                                                       | a unique id to give the attachment                                                                                                                                                                                                                                                     |
| attachments\[].title  | string                     |                                                                       | A title to give the attachment                                                                                                                                                                                                                                                         |
| attachments\[].url    | string                     |                                                                       | a url link to the attachment                                                                                                                                                                                                                                                           |
| description           | string                     |                                                                       | The remittence info to send as part of the payment                                                                                                                                                                                                                                     |
| execution             | object                     |                                                                       | specifies info for the executing date                                                                                                                                                                                                                                                  |
| execution.type        | string                     | SEND, LAND                                                            | Does the date refer to the date the funds should arrive (LAND) or the date the funds should be sent (SEND), defaults to amount.type (future support)                                                                                                                                   |
| execution.date        | string                     | date-time                                                             | The date this payment should be sent on (for SEND payments) or the date this payment should arrive by (for LAND payments)                                                                                                                                                              |
| execution.margin      | integer                    |                                                                       | number of hours before execution date, this payment may be sent if funds exist                                                                                                                                                                                                         |
| final                 | object                     |                                                                       | Properties describing the finalization of this payment details                                                                                                                                                                                                                         |
| final.is\_final       | boolean                    |                                                                       | is the amount final                                                                                                                                                                                                                                                                    |
| final.expected        | string                     | date-time                                                             | If the amount is not final yet, when is the final amount expected                                                                                                                                                                                                                      |
| id                    | string                     |                                                                       | The unique id of the payment                                                                                                                                                                                                                                                           |
| info                  | object                     |                                                                       | Extra info on the payment and its execution                                                                                                                                                                                                                                            |
| info.status           | PaymentRequestStatusEnum   | PENDING, COMPLETED, FAILED, PROCESSING, PARTIAL, CANCELLED, PROCESSED | The current payment status                                                                                                                                                                                                                                                             |
| info.credit           | object                     |                                                                       | If the payment has been processed, holds the amount credited                                                                                                                                                                                                                           |
| info.credit.currency  | string                     | /^\[A-Z]{3}$/                                                         | the 3 letter ISO currency code this payment will be credited in                                                                                                                                                                                                                        |
| info.credit.amount    | number                     |                                                                       | The amount credited                                                                                                                                                                                                                                                                    |
| info.funding          | object                     |                                                                       | If the payment has not been processed yet, holds information about the funding requirments                                                                                                                                                                                             |
| info.funding.currency | string                     | /^\[A-Z]{3}$/                                                         | the 3 letter ISO currency code this amount is to be funded in                                                                                                                                                                                                                          |
| info.funding.amount   | number                     |                                                                       | The amount required to fund                                                                                                                                                                                                                                                            |
| info.funding.date     | string                     | date-time                                                             | The date the funding amount must arrive in the wallet by for this payment to execute on time                                                                                                                                                                                           |
| info.debit            | object                     |                                                                       | The amount to be debited to wallet                                                                                                                                                                                                                                                     |
| info.debit.currency   | string                     | /^\[A-Z]{3}$/                                                         | the 3 letter ISO currency code this payment will be debited in                                                                                                                                                                                                                         |
| info.debit.amount     | number                     |                                                                       | The amount debited                                                                                                                                                                                                                                                                     |
| info.rate             | number                     |                                                                       | FX rate applied to this payment (when cross currency)                                                                                                                                                                                                                                  |
| info.fees             | number                     |                                                                       | Total amount (in debiting currency) of the debited amount collected as a transactional fee                                                                                                                                                                                             |
| purpose               | string                     | /^\[A-Z]{4}$/                                                         | the purpose of the payment as a 4 letter iso-20022 code. see: <[![](https://www.iso20022.org/themes/custom/iso20022_theme/images/favicon/favicon-32x32.png)External code sets \| ISO20022](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets) |
| source                | PaymentRequestMethodEntity |                                                                       | source method                                                                                                                                                                                                                                                                          |
| source.id             | string                     |                                                                       | the id of the entity                                                                                                                                                                                                                                                                   |
| source.type           | string                     |                                                                       | the type of the entity                                                                                                                                                                                                                                                                 |
| target                | object                     |                                                                       |                                                                                                                                                                                                                                                                                        |
| target.type           | string                     |                                                                       | the type of the entity                                                                                                                                                                                                                                                                 |
| target.id             | string                     |                                                                       |                                                                                                                                                                                                                                                                                        |
| type                  | string                     | payment                                                               | entity type (payment)                                                                                                                                                                                                                                                                  |
| user\_tags            | object                     |                                                                       | A set of key/value pairs to tag the payment with                                                                                                                                                                                                                                       |

**Request Example**

```json
PUT /payments/payments/NaxRjIDrRueABiPN-VSkOg
{
   "target": {
      "id": "1"
   },
   "source": {
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b"
   },
   "amount": {
      "type": "LAND",
      "amount": 7000
   },
   "execution": {
      "date": "2024-03-02T09:09:51.508859936Z"
   },
   "final": {
      "is_final": true
   },
   "approved": true
}
```

**Response Examples**

{% tabs %}
{% tab title="200 - OK" %}

```json
{
   "id": "NaxRjIDrRueABiPN-VSkOg",
   "purpose": "SALA",
   "source": {
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
      "type": "group"
   },
   "target": {
      "type": "contact",
      "id": "1"
   },
   "info": {
      "funding": {
         "currency": "USD",
         "amount": 7000
      },
      "status": "PENDING",
      "credit": {
         "currency": "USD",
         "amount": 7000
      },
      "fees": 0
   },
   "amount": {
      "type": "LAND",
      "amount": 7000
   },
   "execution": {
      "date": "2024-03-02T09:09:51Z"
   },
   "final": {
      "is_final": true
   },
   "attachments": [],
   "approved": true,
   "user_tags": {}
}
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```json
{
  "error": "bad_request",
  "description": "Validation errors: {\"type\":\"INDIVIDUAL\",\"id\":\"5SYjAkHqXHW0Z2cqBRW4JAAA\",\"cou... at root failed with \"Missing property org_id\"",
  "error_code": 400
}
```

{% endtab %}
{% endtabs %}

&#x20;