Payments API

The Payment Initiation Service (PIS) API allows you to initiate domestic and international payments on behalf of customers with their explicit consent.

Payment Flow

The payment initiation flow involves these steps:

1
Create Payment Consent
Request consent for the specific payment details
2
Customer Authorization
Redirect customer to authorize the payment
3
Initiate Payment
Submit the payment for processing
4
Track Status
Monitor payment status until settlement

Single Use Consent

Payment consents are single-use. Once a payment is initiated, the consent is consumed and cannot be reused.

Domestic Payments

Domestic payments support UK payment schemes including Faster Payments, BACS, and CHAPS.

Initiate Domestic Payment

POST/open-banking/v1/domestic-payments

Initiate a new domestic payment.

Request

{
  "consent_id": "consent_pay_12345",
  "initiation": {
    "instruction_id": "instr_abc123",
    "end_to_end_id": "e2e_xyz789",
    "local_instrument": "FPS",
    "instructed_amount": {
      "amount": "100.00",
      "currency": "GBP"
    },
    "debtor_account": {
      "scheme": "SortCodeAccountNumber",
      "id": "608371-12345678",
      "name": "John Smith"
    },
    "creditor_account": {
      "scheme": "SortCodeAccountNumber",
      "id": "123456-87654321",
      "name": "Jane Doe"
    },
    "remittance_information": {
      "unstructured": "Invoice payment #1234",
      "reference": "INV-1234"
    }
  },
  "risk": {
    "payment_context_code": "EcommerceGoods",
    "merchant_category_code": "5411"
  }
}

Response

{
  "payment_id": "pay_dom_abc123",
  "consent_id": "consent_pay_12345",
  "status": "accepted_settlement_in_process",
  "creation_date_time": "2024-01-15T14:30:00Z",
  "status_update_date_time": "2024-01-15T14:30:01Z",
  "initiation": {
    "instruction_id": "instr_abc123",
    "end_to_end_id": "e2e_xyz789",
    "local_instrument": "FPS",
    "instructed_amount": {
      "amount": "100.00",
      "currency": "GBP"
    },
    "creditor_account": {
      "scheme": "SortCodeAccountNumber",
      "id": "123456-87654321",
      "name": "Jane Doe"
    }
  },
  "charges": []
}

Local Instruments

Field	Type	Description
`FPS`	string	Faster Payments - real-time, up to £1M
`BACS`	string	BACS - 3 working days, no limit
`CHAPS`	string	CHAPS - same-day, no limit

Get Domestic Payment

GET/open-banking/v1/domestic-payments/{paymentId}

Retrieve the status of a domestic payment.

Request

GET /open-banking/v1/domestic-payments/pay_dom_abc123
Authorization: Bearer {access_token}

Response

{
  "payment_id": "pay_dom_abc123",
  "consent_id": "consent_pay_12345",
  "status": "accepted_settlement_completed",
  "creation_date_time": "2024-01-15T14:30:00Z",
  "status_update_date_time": "2024-01-15T14:30:05Z",
  "initiation": {
    "instruction_id": "instr_abc123",
    "end_to_end_id": "e2e_xyz789",
    "instructed_amount": {
      "amount": "100.00",
      "currency": "GBP"
    }
  }
}

International Payments

International payments support cross-border transfers with currency conversion capabilities.

Initiate International Payment

POST/open-banking/v1/international-payments

Initiate a new international payment.

Request

{
  "consent_id": "consent_int_67890",
  "initiation": {
    "instruction_id": "instr_int_456",
    "end_to_end_id": "e2e_int_789",
    "instructed_amount": {
      "amount": "500.00",
      "currency": "EUR"
    },
    "exchange_rate_information": {
      "unit_currency": "GBP",
      "rate_type": "Indicative"
    },
    "debtor_account": {
      "scheme": "IBAN",
      "id": "GB33BUKB60837112345678",
      "name": "John Smith"
    },
    "creditor": {
      "name": "Hans Mueller",
      "account": {
        "scheme": "IBAN",
        "id": "DE89370400440532013000"
      },
      "postal_address": {
        "street_name": "Hauptstrasse",
        "building_number": "123",
        "post_code": "10115",
        "town_name": "Berlin",
        "country": "DE"
      }
    },
    "creditor_agent": {
      "scheme": "BICFI",
      "id": "COBADEFFXXX",
      "name": "Commerzbank AG"
    },
    "purpose": "SALA",
    "charge_bearer": "SHAR",
    "remittance_information": {
      "unstructured": "Consulting services Q4 2023"
    }
  }
}

Response

{
  "payment_id": "pay_int_xyz789",
  "consent_id": "consent_int_67890",
  "status": "accepted_settlement_in_process",
  "creation_date_time": "2024-01-15T15:00:00Z",
  "status_update_date_time": "2024-01-15T15:00:02Z",
  "initiation": {
    "instruction_id": "instr_int_456",
    "end_to_end_id": "e2e_int_789",
    "instructed_amount": {
      "amount": "500.00",
      "currency": "EUR"
    }
  },
  "exchange_rate_information": {
    "unit_currency": "GBP",
    "exchange_rate": 0.8534,
    "rate_type": "Indicative"
  },
  "charges": [
    {
      "charge_bearer": "SHAR",
      "type": "TransferFee",
      "amount": {
        "amount": "5.00",
        "currency": "GBP"
      }
    }
  ]
}

Charge Bearer Options

Field	Type	Description
`SHAR`	string	Shared - charges split between sender and receiver
`DEBT`	string	Debtor pays all charges
`CRED`	string	Creditor pays all charges

Exchange Rate Types

Field	Type	Description
`Agreed`	string	Pre-agreed rate (requires contract_identification)
`Actual`	string	Rate at time of execution
`Indicative`	string	Estimated rate, may change

Get International Payment

GET/open-banking/v1/international-payments/{paymentId}

Retrieve the status of an international payment.

Payment Status

Payments transition through the following statuses:

Status	Description	Final
pending	Payment created, awaiting processing	No
accepted_settlement_in_process	Payment accepted, settlement in progress	No
accepted_settlement_completed	Payment settled successfully	Yes
rejected	Payment rejected by bank	Yes
cancelled	Payment cancelled by TPP or customer	Yes

Idempotency

Payment requests are idempotent based on the instruction_id field. If you submit the same instruction_id twice, the second request will return the existing payment instead of creating a duplicate.

Best Practice

Always generate a unique instruction_id for each payment attempt. Use UUIDs or another guaranteed unique identifier.

Error Responses

Common error responses for the Payments API:

400

invalid_request

Malformed request body

400

invalid_amount

Invalid amount format

401

invalid_consent

Consent not found or expired

403

wrong_consent_type

This endpoint requires a payment consent

403

consent_not_active

Consent has not been authorized

403

account_not_owned

Debtor account not owned by customer

404

payment_not_found

Payment not found