Ctrl+K

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.

The endpoint currently supports SEPA, SEPA Instant and SWIFT (international) payments.

Note

All these endpoints require authentication, see the authentication documentation for the full list of headers required for these endpoints.

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",
        "bic": "HOLVFIHH",
        "account_identifier": "FI7979977991294922",
        "account_identifier_type": "iban",
        "street": "Some street",
        "country": "FI",
        "additional_info": "Address line 1"
    },
    "method": "sepa"
}

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",
        "street": "Some street",
        "country": "FI",
        "additional_info": "Address line 1"
    }
}

Parameters:

  • <string> payment_account: Payment account UUID

  • <string> amount: Payment amount

  • <string> currency: (optional) ISO 4217 currency code (e.g. EUR). Defaults to the currency of the given payment_account. See list of supported currencies here.

  • <json> counterparty: Payment receiver.

    • <string> name: Name of the counterparty.

    • <string> account_identifier: Either the IBAN or the national account number.

    • <string> account_identifier_type: Allowed types are iban and national_account_number.

    • <string> bic: (optional) BIC of the counterparty. Required if method is international.

    • <string> street: (optional) Street name. Required if method is international.

    • <string> country: (optional) ISO 3166-1 alpha-2 country code. Required if method is international.

    • <string> additional_info: (optional) Additional address information.

  • <date> due_date: ISO 8601 date string

  • <string> unstructured_reference: Max length of 140 characters

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

  • <string> method: (optional) Allowed methods are sepa and international. Defaults to sepa.

  • <string> instant: (optional) Set to true to request a SEPA Instant payment. Defaults to false. It can only be used when method is set to sepa.

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

  • 403: Forbidden. The user does not have permission to perform this action.

    • Permissions granted to the user do not include payment initiation.

    • The user is not verified.

On this page