> 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/initiate-payment-instruction.md).

# Create Payment Instruction

The API creates payment Instructions and enables you to transfer funds to the registered beneficiary.

<mark style="color:green;">**`POST`**</mark> /payments/payments

**Body parameters - Request**

<table data-full-width="false"><thead><tr><th>Name</th><th>Location</th><th>Type</th><th>Format / Values</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>correlation_id</td><td>body</td><td>string</td><td>Up to 100 characters. Alphanumeric, hyphens, and underscores recommended.</td><td>Your own reference ID for this payment. Use it to link Papaya's payment records to your internal system (e.g. your payroll run ID, invoice number, or row reference).</td><td> </td></tr><tr><td>description</td><td>body</td><td>string</td><td> </td><td>The remittance info to send as part of the payment</td><td> </td></tr><tr><td>purpose</td><td>body</td><td>string</td><td>/^([A-Z]{4})$/</td><td>the purpose of the payment as a 4 letter iso-20022 code. see: &#x3C;<a href="https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets"><img src="https://www.iso20022.org/themes/custom/iso20022_theme/images/favicon/favicon-32x32.png" alt="">External code sets | ISO20022</a></td><td>No, defaults to <code>SALA</code></td></tr><tr><td>source</td><td>body</td><td>object</td><td> </td><td> </td><td>Yes</td></tr><tr><td>source.type</td><td>body</td><td>string</td><td>group</td><td>type of source (must be group)</td><td> </td></tr><tr><td>source.id</td><td>body</td><td>string</td><td> </td><td> </td><td>Yes</td></tr><tr><td>target</td><td>body</td><td>object</td><td> </td><td> </td><td>Yes</td></tr><tr><td>target.type</td><td>body</td><td>string</td><td>contact</td><td> </td><td> </td></tr><tr><td>target.id</td><td>body</td><td>string</td><td> </td><td>The id of the target entity (beneficiary)</td><td>Yes</td></tr><tr><td>approved</td><td>body</td><td>boolean</td><td> </td><td>Set to true to mark the payment as approved and ready to be executed</td><td> </td></tr><tr><td>amount</td><td>body</td><td>object</td><td> </td><td>Specifies the amount of the payment</td><td>Yes</td></tr><tr><td>amount.type</td><td>body</td><td>string</td><td>LAND, SEND</td><td>Does the amount refer to the amount credited (LAND), or the amount debited (SEND)</td><td> </td></tr><tr><td>amount.amount</td><td>body</td><td>number</td><td> </td><td>The amount (up to 3 decimal points)</td><td>Yes</td></tr><tr><td>amount.currency</td><td>body</td><td>string</td><td>/^[A-Z]{3}$/</td><td>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</td><td> </td></tr><tr><td>execution</td><td>body</td><td>object</td><td> </td><td>specifies info for the executing date</td><td>Yes</td></tr><tr><td>execution.type</td><td>body</td><td>string</td><td>SEND, LAND</td><td>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)</td><td> </td></tr><tr><td>execution.date</td><td>body</td><td>string</td><td>date-time</td><td>The date this payment should be sent on (for SEND payments) or the date this payment should arrive by (for LAND payments)</td><td>Yes</td></tr><tr><td>execution.margin</td><td>body</td><td>integer</td><td> </td><td>number of hours before execution date, this payment may be sent if funds exist</td><td> </td></tr><tr><td>final</td><td>body</td><td>object</td><td> </td><td>Properties describing the finalization of this payment details</td><td> </td></tr><tr><td>final.is_final</td><td>body</td><td>boolean</td><td> </td><td>is the amount final</td><td> </td></tr><tr><td>final.expected</td><td>body</td><td>string</td><td>date-time</td><td>If the amount is not final yet, when is the final amount expected</td><td> </td></tr><tr><td>attachments</td><td>body</td><td>array</td><td>object</td><td>List of files to attach to the payment</td><td> </td></tr><tr><td>attachments[].id</td><td>body</td><td>string</td><td> </td><td>a unique id to give the attachment</td><td> </td></tr><tr><td>attachments[].title</td><td>body</td><td>string</td><td> </td><td>A title to give the attachment</td><td> </td></tr><tr><td>attachments[].url</td><td>body</td><td>string</td><td> </td><td>a url link to the attachment</td><td>Yes</td></tr><tr><td>user_tags</td><td>body</td><td>object</td><td> </td><td>A set of key/value pairs to tag the payment with</td><td> </td></tr></tbody></table>

**Body parameters -** **Response**

| Name                  | Type                       | Format / Values                                                       | Description                                                                                                                                                                                                                                                                            |
| --------------------- | -------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| correlation\_id       | string                     |                                                                       |                                                                                                                                                                                                                                                                                        |
| 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
POST /payments/payments
{
   "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="202 - Accepted" %}

```json
{
   "id": "NaxRjIDrRueABiPN-VSkOg",
   "correlation_id": "c7c15eb4-8536-4d0b-be81-3bdcbf8bddba",
   "purpose": "SALA",
   "source": {
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
      "type": "group"
   },
   "target": {
      "type": "contact",
      "id": "93219-370c-4567-ab57-dc40d9c78294"
   },
   "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;