Payment Initiation

These endpoints allow TPP to initiate a payment from one of the payment accounts of a Holvi customer.

After initiating a payment, the customer must complete the payment verification process by performing Strong Customer Authentication (SCA) on their phone. You can poll the payment state, upon verification the state will change to verified.

Note

All these endpoints are authenticated. See the authentication documentation for the full list of headers required for this endpoint.

POST /api/v2/payment-initiation/

Example request:

POST /api/v2/payment-initiation/ HTTP/1.1
Accept: application/json
Authorization: Bearer testJWTAccessToken

{
    "payment_account": "b06d5478-0954-451a-a1e0-f1eeb25336be",
    "amount": "100.00",
    "unstructured_reference": "Concert ticket",
    "counterparty": {
        "name": "Jean Sibelius",
        "account_identifier": "FI7979977991294922",
        "bic": "HOLVFIHH"
    }
}

Example response:

HTTP/1.1 201 CREATED
Vary: Accept
Content-Type: application/json

{
    "uuid": "b923d102-127e-449a-a216-960836a229c5",
    "amount": "100.00",
    "currency": "EUR",
    "method": "sepa",
    "booking_date": null,
    "due_date": null,
    "execution_at": null,
    "state": "unverified",
    "direction": "out",
    "is_credit": null,
    "structured_reference": "",
    "unstructured_reference": "Concert ticket",
    "end_to_end_id": "",
    "counterparty": {
        "name": "Jean Sibelius",
        "bic": "HOLVFIHH",
        "account_identifier": "FI7979977991294922",
        "account_identifier_type": "iban"
    }
}

Parameters:

• <json> counterparty: Payment receiver

• <date> due_date: ISO 8601 date string

• <string> payment_account: Payment account UUID

• <string> unstructured_reference: Max length of 140 characters

• <string> end_to_end_id: (optional) Max length of 36 characters

Request Headers:

• Host: Must be psd2.holvi.com

• Date: Must follow the format described in section 7.1.1.1 of RFC 7231

• Digest: See authentication documentation for more details

• Signature: See authentication documentation for more details

• X-Holvi-Client-Id: Client ID provided by Holvi

• X-Holvi-Client-Secret: Client secret provided by Holvi

• Authorization: JWT token to authenticate

Status Codes:

• 201: No error

• 401: Unsuccessful authentication