Single Payments - Yapily Docs

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

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 for more information.

"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 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	The payer(debtor) name is required to make the payment.
Ireland	No
Netherlands	No	Handelsbanken Netherlands	The payer(debtor) account identifications with country is required to make the payment for Handelsbanken - Netherlands
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.

Europe
UK

"paymentRequest": {
  ...
  "payer": {
    "name": "John Doe",
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "DE12345678901234567890"
      }
    ]
  }
}

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

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 as well as the following additional properties in the PaymentRequest. 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 value.

For all countries the payee.accountIdentifications object must contain an IBAN for international payments.

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

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.

​Introduction

​Domestic single payments

​Payer details

​SEPA payments

​International single payments

​Charges

Introduction

Domestic single payments

Payer details

SEPA payments

International single payments

Charges