Transfer funds

In Banqup, you can use payment APIs to transfer money from one account to another.
This API recipe guides you through the complete payment life cycle, including transaction initiation, status tracking, and payment details retrieval.

Prerequisites

The resource IDs necessary to perform the API calls below are:

Step 1: Execute the transfer

Endpoint: POST /payments/v1/spaces/{spaceId}/payments

Request body: View documentation

Path parameter:

spaceId

curl -L -X POST 'https://{{serverURL}}/payments/v1/spaces/:spaceId/payments' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
--data-raw '{
  "bulk": true,
  "debtorAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "language": "en",
  "payments": [
    {
      "amount": {
        "currency": "EUR",
        "value": "10.05"
      },
      "creditor": {
        "account": {
          "bank": {
            "identifier": "3504010119715",
            "scheme": "BIC"
          },
          "country": "BE",
          "currency": "EUR",
          "identifier": "BE83504010119715",
          "scheme": "IBAN"
        },
        "name": "Company XYZ"
      },
      "endToEndIdentification": "BTX71bdfe0f3e084871bf03d008d489c569",
      "reference": {
        "message": "500/0750/95232",
        "type": "STRUCTURED"
      }
    }
  ],
  "redirectUrl": "https://app.btx.banqup.com/payments/payment-feedback"
}'

Successful response:

{
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "redirectUrl": "http://tpp.pay-nxt.com/public/payments/callback/init?paymentPublicId=c1d00d31-ffac-4c35-afca-0e8645a93f62"
}

Note: The redirect URL is the payment page to which the user is redirected to finalize the payment.

Step 2: Get payment details and status

Once the transfer has been finalized, a confirmation is returned by the payment institution and the status of the payment is visible in Banqup.

Endpoint: GET /payments/v1/spaces/{spaceId}/payments/{paymentId}

Path parameter: View documentation

spaceId
paymentId

curl -L -X GET 'https://{{serverURL}}/payments/v1/spaces/:spaceId/payments/:paymentId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:

{
  "amount": {
    "currency": "EUR",
    "value": "10.05"
  },
  "children": [
    null
  ],
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "SUCCESSFUL"
}

Possible payment statuses

Error	Description
RECEIVED	Represents the default status right after payment initiation.
OPEN	The payment has been initiated in Banqup, but payment authorization has not yet been granted by the user in the banking/payment app.
SUCCESSFUL	The payment authorization was successfully granted. The bank starts the money flow (instant or scheduled). In this case, the open balance is updated on the document amount (see next step).
FAILED	The payment transaction was not successfully completed. Possible reasons: insufficient funds, incorrect authorization details, network issues, technical errors, currency issues, account restrictions etc.
CANCELED	The payment was canceled by the user.
UNKNOWN	The system cannot identify the payment status.

Prerequisites​

Prerequisites