Skip to content

Payments (payins)

A transaction is one payin from one payer. It is paid only when stage = WRAP_UP and status = COMPLETED; every endpoint here accepts any key type.

Which flow to use

Payment method Flow
BANK_TRANSFER POST /transaction/create-sync → show the returned bank details → payer pays → webhook
OPEN_BANKING, CREDIT_CARD POST /transaction/create → POST /transaction/preauth → redirect the payer to url → webhook

After any webhook, re-read the transaction with GET /transaction/get-one/:id and act on what you read.

Create a transaction

POST /transaction/create (asynchronous, returns { "transaction": {...} } at once) and POST /transaction/create-sync (waits for verification, about 25 seconds at most) take the same body.

Field Required Description
amount yes Integer > 0, minor units
currencyId yes ISO 4217, e.g. EUR
reference yes Your identifier, e.g. an order number. Need not be unique.
paymentMethod yes BANK_TRANSFER, OPEN_BANKING, CREDIT_CARD
type yes PAYMENT for one-off payins
purpose yes GOODS, SERVICES, BILL, PERSON_TO_PERSON, DONATION, CRYPTO_RELATED, TEST, REFUND, OTHER, UNKNOWN
otherPurpose when purpose = OTHER 4–1000 characters
user yes The payer, see below
paymentProviderIds unless routing rules are on Provider ids in priority order, e.g. ["OPENPAYD"]
paymentSystemId no e.g. SEPA. Chosen automatically if omitted.
idempotencyKey recommended UUID v4
resolveSessionId no From resolve-providers, single use
country no Payer country, alpha-2 or alpha-3. If absent, taken from the caller IP.
ip no Payer IP address. Some providers require it.
userBankAccountId when the payment system needs one The payer's registered bank account
externalCode no Exactly 8 digits; some providers match incoming payments by it
useNextPaymentProviderIfMissingFields no If the payer lacks a field one provider needs, try the next provider
comment no Free text

The payer (user). Send either { "id": "<user id>" } for a payer you already created, or the payer's details: email (required), externalUserId (your UUID for the payer), details (firstName, lastName, birthday as YYYY-MM-DD; or name, regNumber, regType for a company) and address (street, town, postCode, country alpha-3, or a single addressLine). A payer with that email is reused as stored; the details you send do not update it. Each provider may require fields such as DATE_OF_BIRTH or POSTAL_CODE; a missing one fails with REQUEST_VALIDATION_FAILED and explanations names it.

POST /api/v1/transaction/create-sync
{
  "amount": 125000,
  "currencyId": "EUR",
  "reference": "ORDER-2026-000481",
  "paymentMethod": "BANK_TRANSFER",
  "paymentSystemId": "SEPA",
  "paymentProviderIds": ["OPENPAYD"],
  "type": "PAYMENT",
  "purpose": "GOODS",
  "idempotencyKey": "4f0c2d0e-8a51-4d6b-9c3e-2b7a9e1f5c10",
  "country": "DE",
  "user": {
    "email": "anna.schmidt@example.com",
    "details": { "firstName": "Anna", "lastName": "Schmidt", "birthday": "1988-03-14" },
    "address": { "street": "Friedrichstrasse 12", "town": "Berlin", "postCode": "10117", "country": "DEU" }
  }
}

Bank transfer: payment instructions

create-sync answers with transactionId, transaction, url (a payer-facing bank-details page) and rawData, the bank details to show the payer:

{
  "transactionId": "8d3f1b52-6a7e-4c1f-9e0a-5b2c4d6e8f10",
  "url": "https://<host>/api/v1/public/bank-details/widget/8d3f1b52-6a7e-4c1f-9e0a-5b2c4d6e8f10",
  "rawData": {
    "paymentSystemId": "SEPA",
    "currencyId": "EUR",
    "bankName": "Example Bank AG",
    "accountHolderName": "Example Merchant GmbH",
    "financialAccountId": "DE89370400440532013000",
    "financialAccountIdType": "IBAN",
    "financialInstitutionCode": "COBADEFFXXX",
    "financialInstitutionCodeType": "BIC",
    "checkoutUrl": null,
    "needsPaidConfirmation": false
  },
  "transaction": { "id": "8d3f1b52-...", "code": "PIN7K2Q9X4M", "stage": "VERIFICATION", "status": "COMPLETED" }
}

Show the payer the amount, currency and reference with these details; the transaction code is a good payment reference. If needsPaidConfirmation is true, ask the payer to confirm the transfer, then call POST /core/confirm-paid. You can fetch the same instructions later with GET /transaction/payment-instructions/:id.

If create-sync times out, the transaction may still exist: repeat the call with the same idempotencyKey to get it.

Open banking and card: preauth and redirect

After create, call POST /transaction/preauth with { "transactionId": "...", "bankId": "..." } (bankId only for providers that ask the payer to choose a bank, from GET /core/open-banking/institutions/:id). The answer carries url: redirect the payer there.

  • If verification has not finished, the answer is { "transactionId": "...", "queued": true }. Call preauth again a few seconds later.
  • A repeated preauth within 1 hour returns the same result; no second payment is created.

The payer returns to the success, failure, pending or cancel URL configured for your provider binding (Payard sets these up with you). When the return passes through Payard, your URL gets a payard=<JWT> parameter, signed HMAC-SHA256 with your application's redirect secret, carrying transactionId, stage, status, amount and currencyId at redirect time. Treat it as a hint for the page you show; the webhook and get-one are the source of truth.

Optional: choose the provider first

POST /transaction/resolve-providers with amount, currencyId, paymentMethod and country returns the providers and payment systems that would be used, plus a resolveSessionId valid for about 10 minutes. Pass it to create as resolveSessionId. If the answer says requiresPaymentSystemChoice: true, let the payer pick one of paymentSystems[].id and send it as paymentSystemId.

Stages and statuses

A transaction has a stage (VERIFICATION → PREAUTH → CAPTURE → WRAP_UP) and a status within it (INITIATED, IN_PROGRESS, ON_HOLD, COMPLETED, CANCELED, DECLINED, BLOCKED, FAILED, EXPIRED, UNKNOWN).

Outcome Rule
Paid stage = WRAP_UP and status = COMPLETED
Unsuccessful FAILED, DECLINED, CANCELED, EXPIRED or BLOCKED, at any stage
Still in progress INITIATED, IN_PROGRESS, ON_HOLD, UNKNOWN

VERIFICATION + COMPLETED only means the instructions are ready; the payer has not paid. A provider can still move a transaction after an unsuccessful status (a late payment), so always act on the latest state. statusReason is free text for operators; do not parse it.

If routing rules with cascading are on and a provider fails, Payard may switch to the next provider: you get a CASCADE_NEW_PAYMENT_PROVIDER_ASSIGNED webhook, and a running create-sync or preauth returns RETRY_WITH (HTTP 449). Repeat that call.

Finding transactions

  • GET /transaction/get-one/:id — one transaction.
  • POST /transaction/get-all — filter body, e.g. { "statuses": ["COMPLETED"], "created": { "startDate": "...", "endDate": "..." } }.

Run a periodic reconciliation over get-all for non-final transactions, to catch anything a webhook did not deliver.