> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Single Payments
> Initiate single domestic and international payments using the Yapily API. Covers payment types, required fields, institution compatibility, and response handling.
## Introduction
A single payment is 1 payment for a specified amount which the end user can configure from an institution to pay an entity.
You can create both domestic and international single payments with the Yapily API.
Looking for our quickest integration option? See [Yapily Hosted Pages](/tools-and-services/hosted-pages/overview) which provides a pre-built and hosted UI to quickly and easily facilitate single payments.
***
## Domestic single payments
Domestic single payments are possible when the institution supports the feature `CREATE_DOMESTIC_SINGLE_PAYMENT`.
To create a single domestic payment, you need to provide the following properties as part of the [paymentRequest object](/api-reference/authorisations/create-payment-authorisation):
| Property | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `type`
*required* | The payment type to use. |
| `paymentIdempotencyId`
*required* | The unique identifier for the payment.
Any alpha-numeric string less than or equal to 35 characters. |
| `amount`
*required* | The monetary value and currency. |
| `payee`
*required* | Details of the beneficiary. |
| `reference`
*optional* | The payment reference or description.
Any string less than 18 characters. |
| `payer`
*conditional* | Details of the benefactor.
See [payer details](#payer-details) for more information. |
```json theme={null}
"paymentRequest": {
"type": "DOMESTIC_PAYMENT",
"paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
"amount": {
"amount": "1.00",
"currency": "GBP"
},
"payee": {
"name": "Jane Doe",
"address": {
"country": "GB"
},
"accountIdentifications": [
{
"type": "SORT_CODE",
"identification": "123456"
},
{
"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"reference": "Bill Payment",
}
```
#### Payer details
Specifying the [payer details](/api-reference/authorisations/create-payment-authorisation#body-payment-request-payer) in the `paymentRequest` object is conditional on the country you are making the payment in.
The **Payer** object is not required in:
| Country | Payer Object Required? | Banking Group | Exceptions/Notes |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Belgium | No | | |
| France | No | [Arkea Group](/institution-configurations/france/Arkea-Group) | The payer(debtor) name is **required** to make the payment. |
| Ireland | No | | |
| Netherlands | No | [Handelsbanken Netherlands](/institution-configurations/netherlands/Handelsbanken-Netherlands) | The payer(debtor) account identifications with country is **required** to make the payment for [Handelsbanken - Netherlands](https://console.yapily.com/institutions/handelsbanken_nl) |
| Portugal | No | | |
| Spain | No | | |
| UK | No | | |
Some banks may require additional information. Please contact our support for details.
**For all other countries in Europe, you must provide the `Payer` object with details of the benefactor.**
You can obtain the payer details by accessing the user's account information using AIS, requesting the details from the user or providing information you have already gathered from the user.
For countries in Europe, the `accountIdentifications` object should just contain the `IBAN`.
In the UK, the `accountIdentifications` object should contain the `ACCOUNT_NUMBER` and `SORT_CODE`.
```json theme={null}
"paymentRequest": {
...
"payer": {
"name": "John Doe",
"accountIdentifications": [
{
"type": "IBAN",
"identification": "DE12345678901234567890"
}
]
}
}
```
```json theme={null}
"paymentRequest": {
...
"payer": {
"name": "John Doe",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{
"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
```
**Note:** If you specify the payer details, this will force the user to make the payment from the specified account.
### SEPA payments
It is also possible to execute SEPA payments as domestic payments.
To find out more, see [European Payments](/payments/payment-resources/european-payments).
***
## International single payments
International payments are currently available as a BETA version.
International single payments are possible when the institution supports the feature `CREATE_INTERNATIONAL_SINGLE_PAYMENT`.
To create an international single payment, you need to provide the properties required for a [domestic single payment](#domestic-single-payments) as well as the following additional properties in the [PaymentRequest](/api-reference/authorisations/create-payment-authorisation).
**Note:** The same additional properties are required for a scheduled or periodic international payment.
| Property | Description |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payee.address`
*conditional* | The address of the payee.
Required when the payment type is international. |
| `internationalPayment`
*conditional* | Specifies the properties to define an international payment.
Must be specified when payment `type`:
`INTERNATIONAL_PAYMENT`,
`INTERNATIONAL_SCHEDULED_PAYMENT`,
`INTERNATIONAL_PERIODIC_PAYMENT` |
| `internationalPayment.currencyOfTransfer`
*required* | The 3 letter currency code for the currency of the payment to be transferred to.
This can differ from the currency of the payer's account. |
| `internationalPayment.chargeBearer`
*optional* | Specifies who should bear the charges associated with processing the payment transaction. |
| `internationalPayment.priority`
*optional* | Specifies the priority of the payment. |
| `internationalPayment.purpose`
*optional* | Indicate the external purpose as a [ISO20022 purpose code](https://www.rba.hr/documents/20182/183267/External+purpose+codes+list/8a28f888-1f83-5e29-d6ed-fce05f428689?version=1.1) value. |
For all countries the `payee.accountIdentifications` object must contain an `IBAN` for international payments.
```json theme={null}
"paymentRequest": {
"type": "INTERNATIONAL_PAYMENT",
"paymentIdempotencyId": "4289457hd38djoa783jw9qag2",
"amount": {
"amount": "1.00",
"currency": "GBP"
},
"payee": {
"name": "Jane Doe",
"address": {
"streetName": "Sample Street",
"buildingNumber": "1",
"postCode": "AB1 2CD",
"country": "GB"
},
"accountIdentifications": [
{
"type": "BIC",
"identification": "RBOSGB2109M"
},
{
"type": "IBAN",
"identification": "GB29RBOS83040210126939"
}
]
},
"reference": "Bill Payment",
"internationalPayment": {
"currencyOfTransfer": "USD",
"chargeBearer": "DEBT",
"priority": "NORMAL",
"purpose": "GDDS"
}
}
```
See more information in the [API reference](/api-reference/payments/create-payment).
#### Charges
International payments are executed with cross-border charges. These are passed on to the user and should be displayed by the institution once the user is redirected to give their authorisation.