curl --request POST \
  --url https://api.yapily.com/payment-auth-requests \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --data '
{
  "applicationUserId": "string",
  "institutionId": "bpm-sandbox",
  "callback": "https://display-parameters.com/",
  "paymentRequest": {
    "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "reference": "Bill Payment",
    "type": "DOMESTIC_PAYMENT",
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "BE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "BE12345678901234"
        }
      ]
    }
  }
}
'

{
  "meta": {
    "tracingId": "a3d09f97bea244e2bb8be0bffbe53f81"
  },
  "data": {
    "id": "cae22f3d-1033-4ba6-95ae-0d8ca193b090",
    "userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
    "applicationUserId": "string",
    "institutionId": "bpm-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-10T11:47:12.887Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "state": "6a5f69be6a084b5c8c1becac88d45c95",
    "institutionConsentId": "79cee256-077f-4e11-a307-43892646a4a6",
    "authorisationUrl": "https://scasandbox.bancobpm.it/sca/login.html?paymentId=79cee256-077f-4e11-a307-43892646a4a6&tppAuthenticationRedirectUri=https%3A%2F%2Fauth.yapily.com%2F%3Ftwofold_redirect%3Dtrue%26state%3D6a5f69be6a084b5c8c1becac88d45c95&tppName=YAPILY+LTD&aspspCode=05034&aspspProductCode=IBP01&tppRegistrationNumber=PSDGB-FCA-927459&hash=GY5CmKG3MVeoxrboUQkjCoIb1X0nGR9ZTfoIG3T%2FLx1At1UJ92w0sjDeRXbNP9NhO203Y03UeI6Xn9ThebOjtQ%3D%3D",
    "qrCodeUrl": "https://images.yapily.com/image/5955c0db-a5b7-4b12-a682-0f83317ba46d/1623325632?size=0"
  }
}

Authorisations

Create Payment Authorisation

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a payment. This endpoint is used to initiate all the different payment listed below. Based on the type of payment you wish to make, you may be required to provide specific properties in PaymentRequest. First make sure that the payment feature you wish to execute is supported by the bank by checking the features array in GET Institution.

Features:

INITIATE_DOMESTIC_PERIODIC_PAYMENT
INITIATE_DOMESTIC_SCHEDULED_PAYMENT
INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
INITIATE_DOMESTIC_SINGLE_PAYMENT
INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
INITIATE_INTERNATIONAL_SINGLE_PAYMENT

curl --request POST \
  --url https://api.yapily.com/payment-auth-requests \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --data '
{
  "applicationUserId": "string",
  "institutionId": "bpm-sandbox",
  "callback": "https://display-parameters.com/",
  "paymentRequest": {
    "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "reference": "Bill Payment",
    "type": "DOMESTIC_PAYMENT",
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "BE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "BE12345678901234"
        }
      ]
    }
  }
}
'

{
  "meta": {
    "tracingId": "a3d09f97bea244e2bb8be0bffbe53f81"
  },
  "data": {
    "id": "cae22f3d-1033-4ba6-95ae-0d8ca193b090",
    "userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
    "applicationUserId": "string",
    "institutionId": "bpm-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-10T11:47:12.887Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "state": "6a5f69be6a084b5c8c1becac88d45c95",
    "institutionConsentId": "79cee256-077f-4e11-a307-43892646a4a6",
    "authorisationUrl": "https://scasandbox.bancobpm.it/sca/login.html?paymentId=79cee256-077f-4e11-a307-43892646a4a6&tppAuthenticationRedirectUri=https%3A%2F%2Fauth.yapily.com%2F%3Ftwofold_redirect%3Dtrue%26state%3D6a5f69be6a084b5c8c1becac88d45c95&tppName=YAPILY+LTD&aspspCode=05034&aspspProductCode=IBP01&tppRegistrationNumber=PSDGB-FCA-927459&hash=GY5CmKG3MVeoxrboUQkjCoIb1X0nGR9ZTfoIG3T%2FLx1At1UJ92w0sjDeRXbNP9NhO203Y03UeI6Xn9ThebOjtQ%3D%3D",
    "qrCodeUrl": "https://images.yapily.com/image/5955c0db-a5b7-4b12-a682-0f83317ba46d/1623325632?size=0"
  }
}

Learn more: Single Redirect Flow

Authorizations

Authorization

string

header

required

Use HTTP Basic Authentication with your Application ID as username and Application Secret as password. Manage credentials in the Yapily Console. See Authentication for details.

Headers

psu-id

string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id

string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address

string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application

string<uuid>

The sub-application ID to which event type is being subscribed to

Body

application/json;charset=UTF-8

The request body containing an PaymentAuthorisationRequest json payload

institutionId

string

required

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

Example:

"yapily-mock"

paymentRequest

object

required

Mandatory. The payment request object defining the details of the payment.

Show child attributes

userUuid

string<uuid>

applicationUserId

string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

Example:

"user-234562290"

forwardParameters

string[]

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

callback

string

Optional. The URL to redirect the user to after the user complete the authorisation at the Institution.

Example:

"https://display-parameters.com"

redirect

object

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

Show child attributes

oneTimeToken

boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

Example:

false

Response

Created

Getting Started

Authorisations

Financial Data

Payments

Consents

Institutions

Users

Notifications

Variable Recurring Payments

Data Plus

Hosted Consent Pages

Hosted Payment Pages

Constraints

Application Management

Webhooks

Application Beneficiaries

User Beneficiaries

Create Payment Authorisation

Authorizations

Headers

Body

Response