Collect Payment

Given a user’s online banking credentials, the Collect Payment Service allows to let users initiate pre-defined payments.

Do not use this service to initiate user-defined payments.

sequenceDiagram actor User participant YAXI participant Your Backend participant Bank User->>+Your Backend: Ticket request Your Backend-->>User: Ticket with payment details (ID, customer's bank, amount, recipient) rect rgb(243, 243, 243) note right of User: Encrypted and verified channel User->>+YAXI: Ticket YAXI->>+YAXI: Verify authenticity YAXI-->>-User: Bank login form User->>+YAXI: Send login credentials end YAXI->>+Bank: Initiate payment opt Strong Customer Authentication Bank-->>-User: Request authorization User->>+Bank: Authorize end Bank-->>-YAXI: OK YAXI-->>-User: OK User->>+Your Backend: OK Your Backend->>+Your Backend: Verify authenticity Your Backend-->>-User: OK

Issue a service ticket

Use CollectPayment as a service identifier when issuing tickets. The service expects the following ticket data:

Restrictions on remittance and creditor name:

Some banks require a minimum remittance of a few characters.
Long texts may be truncated, typically with a limit of 140 characters for remittance and 70 for the creditor name.
Providers accept different character sets for the creditor name and remittance. The safe baseline is:
```
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
/-?:().,' +
Space
```
Other characters may be accepted, rejected, stripped or replaced.

The service officially only supports payments in EUR to creditor accounts within the eurozone. Payments with other currencies and receivers (within the Single Euro Payments Area) should generally work, though. Use them at your own risk, but feel free to report any issues. Also do not hesitate to contact us to discuss specific requirements.

Issue a service ticket:

Python
Java
Rust
PHP

ticket_id = str(uuid.uuid4())
ticket = issue_ticket(
    ticket_id,
    "CollectPayment",
    {
        "amount": {
            "amount": "100",
            "currency": "EUR",
        },
        "creditorAccount": {
            "iban": COMPANY_IBAN,
        },
        "creditorName": COMPANY_NAME,
        "remittance": f"Sign-up fee {PRODUCT_NAME} {customer_id}",
    },
)

String ticketId = UUID.randomUUID().toString();
String ticket = issueTicket(
    ticketId,
    "CollectPayment",
    Map.of(
        "amount", Map.of(
            "amount", "100",
            "currency", "EUR"
        ),
        "creditorAccount", Map.of(
            "iban", COMPANY_IBAN
        ),
        "creditorName", COMPANY_NAME,
        "remittance", "Sign-up fee " + PRODUCT_NAME + " " + customer_id
    )
);

let ticket_id = Uuid::new_v4().to_string();
let ticket = issue_ticket(
    &ticket_id,
    "CollectPayment",
    json!({
        "amount": {
            "amount": "100",
            "currency": "EUR",
        },
        "creditorAccount": {
            "iban": COMPANY_IBAN,
        },
        "creditorName": COMPANY_NAME,
        "remittance":
            format!("Sign-up fee {PRODUCT_NAME} {customer_id}")
    }),
)?;

$ticketId = uniqid();
$ticket = issueTicket(
    $ticketId,
    "CollectPayment",
    json_encode([
        'amount' => [
            'amount': '100',
            'currency': 'EUR',
        ],
        'creditorAccount' => [
            'iban' => $COMPANY_IBAN,
        ],
        'creditorName' => $COMPANY_NAME,
        'remittance' => 'Sign-up fee '.$PRODUCT_NAME.' '.$customerId,
    ])
);

Call the service

The client accepts the following arguments:

An optional debtor account.

This could be provided by the user, known from a previous transaction, or gathered from the accounts service.

If no debtor account is provided, a selection dialog may be returned, depending on the bank. This dialog indicates the Accounts context and provides options for each possible IBAN. If the list contains only a single element, its main purpose is to inform the client of the IBAN (e.g., for future use), and the response can be automated. For building a richer user selection dialog, we recommend using the accounts service beforehand (please contact us if this service is not included in your plan).

Refer to your client library for details and documentation.

Call the service:

JavaScript
Kotlin
Rust

await client.collectPayment({
  credentials,
  ticket,
  account: {
    iban: "NL58YAXI1234567890",
    currency: "EUR"
  }
})

client.collectPayment(
    credentials,
    ticket = ticket,
    account = AccountReference(
        AccountIdentifier.Iban("NL58YAXI1234567890"),
        currency = "EUR",
    ),
)

client.collect_payment(
    credentials,
    None,
    ticket,
    Some(AccountReference {
        id: AccountIdentifier::Iban("NL58YAXI1234567890".to_string()),
        currency: Some("EUR".to_string()),
    }),
).await?;

Result

A successful response from the service confirms that the user’s bank has initiated the payment using the properties specified in the ticket you previously issued in your backend. This means that the user has authorized the payment and has neither canceled nor rejected it. Finally, you forward the result to your backend system to reconcile its data with the ticket after verifying its authenticity.

The service currently does not provide a transaction status, but we plan to add this in the future. Feel free to contact us to discuss any specific requirements.

Recovery

If your frontend is unable to retrieve (or forward) the final response, you can use the ticket to request the last status from the service. The service retains the status for about 15 minutes and exposes it via an HTTP endpoint:

Method: POST
Path: /collect-payment/status
Headers: YAXI-Ticket

curl example

curl -X POST --header 'YAXI-Ticket: <JWT>' \
  https://api.yaxi.tech/collect-payment/status