menu

Payment API

What's on this page

Online Payments / Payment Methods / Banktransfer

Banktransfer

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

Introduction

Bank transfer (also known as Wire transfer) is a payment method that allows a customer to transfer funds from one bank account to another. The customer is provided with the information to complete the payment via mail, including the payment reference and bank account number, and can complete afterwards 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 alpha-numeric 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 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

Banktransfer 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 banktransfer 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. Defaults to a maximum of P7D and should be lesser than expirationDuration 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

Banktransfer does not require method specific input.

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