menu

Payment API

What's on this page

Online Payments / Payment Methods / Banktransfer

Bank transfer

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Worldwide ✓ ✓

Introduction

Bank transfer is a payment method that allows a customer to fulfill the payment by transferring funds using his bank account. The information required to complete the payment, is provided to the customer via mail, including the payment reference and bank account number. It can be completed later on using a banking tool of preference.

Guidelines

CCV uses a bank account number for Belgium and the Netherlands as a beneficiary, which is selected depending on the billing country. The bank account is supervised and known as Stichting Derdengelden account.

Depending on the country CCV uses a unique reference for remittance information:

  • Netherlands: a unique alphanumeric string, example B123456789012345
  • Belgium: a structured reference +++344/0660/16938+++

In order to make a bank transfer payment succeed, CCV must receive the money from the customer on CCV’s bank account and the amount and the reference must match.

Warning

If the amount and the reference do not match, CCV refunds the money automatically.

Belgian Structured References

Belgian customers are accustomed to using a structured reference for the remittance information when using a bank transfer. The structured reference aids in automated reconciliation of payments.

  1. Format: The Belgian structured reference follows the “OGM-VCS” standard. It can be either electronic (12 digits) or visual (using plus signs). For example:
    • Electronic: 12 digits (e.g., 010806817183)
    • Visual: +++ 3 digits / 4 digits / 5 digits / +++ (e.g., +++010/8068/17183+++)
  2. Check Digits: The last two digits serve as check digits (computed using modulo 97) based on the first 10 digits. If the result is 0, the check digits are set to 97.

It ensures that adequate remittance information accompanies transactions, facilitating accurate accounting and tracking

Bank transfer expiration

For most payment methods, when the expiration duration is exceeded the payment expires when not completed. For method banktransfer it’s possible that the customer has already completed the payment while the bank is still processing past this duration. A transaction could therefore be expired, but a day or so later the funds would still be transferred. To compensate for bank processing, 2 calendar days are added to the requested expiration duration and the transaction will expire in the morning of the resulting day.

For example:

  • If a payment is created at 01:00 on Monday, with an expiration duration of 3 days resulting in 01:00 on Thursday, and the customer does not complete payment, the transaction will expire Friday morning.
  • If a payment is created at 23:59 on Wednesday, with an expiration duration of 3 days resulting in 23:59 on Saturday, and the customer does not complete payment, the transaction will expire Monday morning.
  • If a payment is created at 01:00 on Monday, with an expiration duration of 2 days resulting in 01:00 on Wednesday, and the customer completes payment on Tuesday and the bank completes processing before Thursday morning, the transaction is completed successfully and reaches status success.

Method API details

Payment

A bank transfer has payment method specific details you may provide. All details have a default value that you can override.

Name Required Description Max Length
expirationDuration No The time until payment expiration in ISO 8601 Duration. Default value is P12D. Absolute maximum is P2M1D. A delay is applied. 20
expirationTimestamp No The epoch timestamp when the payment should expire. Default value is set to 12 days after initial creation. Absolute maximum is 2 months and 1 day. /
mail No A boolean value that indicates to mail the payment instructions. Defaults to true 5
mailReminder No A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true 5
mailReminderDuration No The time until to mail a payment reminder in ISO 8601 Duration, should be lesser than expirationDuration. Defaults to expirationDuration - 1 day with a maximum of P7D 20
allowCustomerCancel No A boolean value to show the cancel link on the bank transfer form. When false the bank transfer form shows a return link to be redirected to the returnUrl instead of a cancel link to cancel and return. Defaults to true 5

Example request

{
  "amount": 9.99,
  "currency": "eur",
  "method": "banktransfer",
  "returnUrl": "https://shop/return?order=123456",
  "webhookUrl": "https://shop/payhook?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng",
  "billingEmail": "first.lastname@email",
  "billingCountry": "NL",
  "details": {
    "expirationDuration": "P0Y0M12DT0H0M0.000S",
    "mail": true,
    "mailReminderDuration": "P0Y0M7DT0H0M0.000S"
  }
}

Example response

{
  "lastUpdate": 1709902146155,
  "created": 1709902146148,
  "billingEmail": "first.lastname@email",
  "billingCountry": "NL",
  "cancelUrl": "https://vpos-test.jforce.be/vpos/api/v1/cancel?reference=B240308134906148CB87E322.L",
  "merchantOrderReference": "123456",
  "paidout": "no",
  "details": {
    "expirationDuration": "P0Y0M12DT0H0M0.000S",
    "mailReminder": true,
    "mail": true,
    "mailReminderDuration": "P0Y0M7DT0H0M0.000S",
    "allowCustomerCancel": true,
    "iban": "NL26INGB0006865503",
    "banktransferReference": "B000003414560513",
    "bic": "INGBNL2A",
    "mailReminderSent": false
  },
  "amount": 9.99,
  "status": "pending",
  "description": "Order 123456",
  "returnUrl": "https://shop/return?order=123456",
  "reference": "B240308134906148CB87E322.L",
  "method": "banktransfer",
  "type": "sale",
  "language": "eng",
  "currency": "eur"
}

These details are possible for a payment using the method banktransfer.

Name Description
expirationDuration The time until payment expiration in ISO 8601 Duration. Default value is P12D. Absolute maximum is P2M1D.
iban The IBAN account number the customer must wire the amount to. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
bic The BIC number of the bank the customer should wire the amount to. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
banktransferReference The reference the customer should use for the bank transfer
mail A boolean value that indicates to mail the payment instructions. Defaults to true
mailReminder A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true
mailReminderDuration The time until to mail a payment reminder in ISO 8601 Duration
allowCustomerCancel A boolean value to show the cancel link on the bank transfer form. When false the bank transfer form shows a return link to be redirected to the returnUrl instead of a cancel link to cancel and return. Defaults to true

Refund

A refund requires a pre-existing payment with method banktransfer and type sale with status success. A refund for a bank transfer does not require any method specific input.

{
  "reference": "B240308134906148CB87E322.L",
  "description": "Refund of Order 123456"
}

Credit

A credit does not require a pre-existing payment with method banktransfer. As a credit is not linked to a previous payment, it does require method specific input to be able to process the credit and transfer the money to the customer.

The consumer does not need to do anything. Once the PSP pays out the credit, the money will be transferred to the consumerAccountNumber and the credit will be completed with status success.

{
  "amount": 9.99,
  "method": "banktransfer",
  "language": "eng",
  "transactionType": "credit",
  "currency": "eur",
  "billingCountry": "NL",
  "details": {
    "consumerAccountNumber": "NL26INGB0006865503",
    "consumerName": "First Lastname"
  }
}

It is important to notice that a credit requires a billing country (billingCountry). The billing country determines from which PSP balance of the merchant account the money will be transferred from.

The method specific details for a bank transfer credit are:

Name Required Description Max Length
consumerName Yes the name of the account holder of the consumerAccountNumber 70
consumerAccountNumber Yes The bank account number (IBAN) to which the money will be transferred 34