menu

Payment API

What's on this page

Online Payments / Basic Operations / Authorise & Capture Payments

Authorise and Capture

An authorise allows a merchant to reserve money from the customer without withdrawing the money from the customers account. When you want to withdraw the money later on, you can send a capture request. If you decide to not withdraw the money, you can send a reversal request to release the reserved money on the customers account.

This can be useful in cases where

  • you want to authorise a payment, but only capture it once the order is ready to be shipped.
  • you want to authorise a fixed amount for fueling to reserve the funds, and capture the actual amount once the fueling is completed.
  • you want to authorise a fixed amount for EV charging to reserve the funds, and capture the actual amount once the charging is completed.
  • you want to authorise a fixed amount on hotel check-in, and capture the actual amount on check-out.

Available Methods

You can view the supported payment methods here.

Knowledge Base

  • An authorisation of a payment is the process of reserving the funds on the customer’s account.
  • An authorisation is valid for a certain period of time, after which it expires.
  • An authorisation can be captured at any time before it expires.
  • The expiration time is specific to the payment method and can be found in the Payment Methods documentation.
  • The funds on the customer’s account are reserved for the authorisation, and the customer cannot spend them, until you capture or reverse the authorisation or the authorisation expires.
  • The default amount for a capture is the full amount of the authorisation, but you can capture a different amount, as long as it does not exceed the authorised amount.

Important

When an authorisation is completed successfully, it is always required to check if there is an authorisedAmount in the transaction details. This is the amount that is reserved on the customer’s account. The authorisedAmount can be different from the requested amount, for example when a card has a limit on the maximum amount that can be authorised. When doing a capture without specifying an amount, the authorisedAmount will be used as the default amount for the capture.

Typical Transaction Flow

Authorise

You want to reserve the funds on the customer’s account for a specific amount for your service you are about to deliver. Usually, the exact amount is not known at this point, so you authorise a fixed amount.

  1. You initiate a new authorisation request
  2. A transaction response is returned
  3. The customer is redirected to the payment page
  4. The customer enters their card details and completes the authentication
  5. PSP sends an authorization to the acquirer.
  6. A transaction result is sent to you (success or failure, through notification or webhook)
  7. You inform the customer of the transaction result

Capture or Reversal

After you have delivered or cancelled the service, you can either capture the authorisation or reverse it.

Important

When the authorisation is completed successfully, it is always required to check if there is an authorisedAmount in the transaction details. When you do not want to proceed with the capture because the authorisedAmount is lower than the requested amount, you can reverse the authorisation to release the reserved funds on the customer’s account.

  1. You initiate a capture or reversal request. Optionally it includes an amount to capture or reverse.
  2. A transaction response is returned
  3. PSP sends the capture or reversal request to the acquirer.
  4. A transaction result is sent to you (success or failure, through notification or webhook) 5.You inform the customer of the transaction result

Authorise the payment

This requires the payment method to support authorisations. The following request will send an authorise request for 9.99 EUR,

  1. Initiate a new payment with type authorise

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "transactionType": "authorise",
  "amount": 9.99,
  "currency": "eur",
  "method": "card",
  "returnUrl": "https://shop/return?order=123456",
  "webhookUrl": "https://shop/payhook?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng"
}' https://api.psp.ccv.eu/api/v1/payment

    Example response

    {
    "lastUpdate": 1709620979582,
    "cancelUrl": "https://onlinepayments.ccv.eu/card/cancel/merchant?reference=C240305064258677CB87E192.G",
    "created": 1709620979582,
    "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C240305064258677CB87E192.G",
    "amount": 9.99,
    "description": "Order 123456",
    "status": "pending",
    "reference": "C240305064258677CB87E192.G",
    "merchantOrderReference": "123456",
    "method": "card",
    "type": "authorise",
    "language": "eng",
    "currency": "eur",
    "returnUrl": "https://shop/return?order=123456"
}

  2. In order to complete the payment, you’ll need to redirect your customer to the payment url (payUrl) as returned in the payment response.

  3. Depending on the payment method, the customer performs an authentication. In case of card payments, we use 3-D Secure to verify the customer’s identity.

  4. As a final result, we return the customer back to your shop. The shop url is provided by you as returnUrl when you initiated the request in step 1.

  5. At this point you don’t know whether the payment is successful or not.

    • You must request the status of the payment in order to complete your order correctly. See also Read a transaction.
    • You must not assume that a return of the customer is due to successful payment!

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=C240305064258677CB87E192.G

    Example response

    {
  "lastUpdate": 1709621105740,
  "statusFinalDate": 1709621105740,
  "cancelUrl": "https://onlinepayments.ccv.eu/card/cancel/merchant?reference=C240305064258677CB87E192.G",
  "created": 1709620979582,
  "methodTransactionId": "tMuzqg",
  "entryMode": "ecom",
  "brand": "visa",
  "details": {
    "cardholderFirstName": "John",
    "initialTransactionId": "p3GNcBD4tLFo800",
    "qrCode": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=1d584a8f-58fc-4704-a92d-9955e678b932&trm=50",
    "maskedPan": "4111XXXXXXXX1111",
    "acquirerResponseCode": "00",
    "urlIntent": "https://shop-vpos-test.ccvlab.eu/bep/authenticate.html?secureTransferId=1d584a8f-58fc-4704-a92d-9955e678b932&trm=51",
    "authorisedAmount": 9.99,
    "acquirer": "Valitor",
    "cardholderLastName": "Doe",
    "authenticationProtocol": "3DS2",
    "authenticationStatus": "Y",
    "acquirerResponseCodeDescription": "ApprovedOrCompletedSuccessfully"
  },
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C240305064258677CB87E192.G",
  "amount": 9.99,
  "description": "Order 123456",
  "status": "success",
  "reference": "C240305064258677CB87E192.G",
  "merchantOrderReference": "123456",
  "method": "card",
  "type": "authorise",
  "language": "eng",
  "currency": "eur",
  "returnUrl": "https://shop/return?order=123456"
}

  6. As a side effect of completing the payment (successfully or not), we will notify you using the webhook provided in step 1.

Capture

  1. When later in time you know the definitive amount to charge, perform a Capture request on the previous authorise transaction. The authorisation reference must be sent in the reference field.

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "amount": 5.31,
  "webhookUrl": "https://shop/payhook?order=123456",
  "description": "Order 123456",
  "reference" : "C240305064258677CB87E192.G"
}' https://api.psp.ccv.eu/api/v1/capture

    Example response

    {
  "lastUpdate": 1709621334602,
  "originalReference": "C240305064258677CB87E192.G",
  "created": 1709621334478,
  "brand": "visa",
  "amount": 5.31,
  "description": "Order 123456",
  "status": "pending",
  "reference": "C240305064854420CB87E193.G",
  "merchantOrderReference": "123456",
  "method": "card",
  "type": "capture",
  "language": "eng",
  "currency": "eur"
}

  2. At this point you don’t know whether the payment is successful or not.

    • You must request the status of the payment in order to complete your order correctly. See also Read a transaction.
    • You must not assume that a return of the customer is due to successful payment!

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=C240305064854420CB87E193.G

    Example response

    {
  "originalReference": "C240305064258677CB87E192.G",
  "lastUpdate": 1709621334942,
  "statusFinalDate": 1709621334942,
  "methodTransactionId": "tMuzqg",
  "entryMode": "ecom",
  "created": 1709621334478,
  "details": {
    "initialTransactionId": "p3GNcBD4tLFo800",
    "acquirerResponseCode": "00",
    "authorisedAmount": 9.99,
    "acquirer": "Valitor",
    "acquirerResponseCodeDescription": "ApprovedOrCompletedSuccessfully"
  },
  "status": "success",
  "description": "Order 123456",
  "brand": "visa",
  "amount": 5.31,
  "merchantOrderReference": "123456",
  "notificationRequests": [],
  "reference": "C240305064854420CB87E193.G",
  "returnUrl": "https://shop/return?order=123456",
  "method": "card",
  "type": "capture",
  "language": "eng",
  "currency": "eur"
}

  3. After effect of completing a payment (successfully or not) we will notify you using a webhook. This allows you to perform additional operations in your system like sending an email to your customer.

Capture Terminal Transactions

When capturing a payment which was made using the method terminal, additional details can be provided if the terminal is different from the original authorisation. Any details included in the original authorise can be overwritten with these details.

Example Request

{
  "amount": 5.31,
  "webhookUrl": "https://shop/payhook?order=123456",
  "description": "Order 123456",
  "reference" : "C240305064258677CB87E192.G",
  "details": {
    "terminalId": "1234567",
    "managementSystemId": "1234567",
    "accessProtocol": "OPI_NL",
    "ip": "192.168.1.154",
    "port": "6235",
    "operatingEnvironment": "ATTENDED",
    "merchantLanguage": "ita"
  }

Capture with Payout Instructions

A payout instruction can be used to provide a custom structured reference and facilitate Split Payouts. Multiple Payout Instructions can only be used when boarded for Split Payout.

Requirements:

  • The sum of all payout instructions must match the capture amount
  • The capture amount for each payout instruction is required
  • Partial Captures on payout instructions are allowed

Example Request

{
  "amount": 5.31,
  "webhookUrl": "https://shop/payhook?order=123456",
  "description": "Order 123456",
  "reference" : "C240305064258677CB87E192.G",
    "payoutInstructions": [
        {
            "amount": 2.00,
            "structuredReference": "090933755493",
            "externalReference" : "0001606469162293"
        },
        {
            "amount": 3.31,
            "structuredReference": "090933755423",
            "externalReference" : "0001606469162223"
        }
    ]
}

Reversal

Depending on the payment method, the following can be accomplished using a reversal:

  • The funds reserved earlier using an authorise request, can be released.
  • A previous sale can be reversed making it appear as if the sale never occurred.

Possibilities

The following transactions can be reversed:

  • authorise transactions
    • For the following methods: applepay, card, googlepay, klarna and terminal.
    • That have not already been captured, and are not in progress of being captured.
  • sale and capture transactions
    • For the following methods: terminal.
    • That have not already been refunded, and are not in progress of being refunded.
  • In addition, only transactions that have not already been previously reversed, and are not in progress of being reversed, can be reversed.

Basic Flow

  1. When you want to cancel the authorisation and release the reserved funds on the customer’s account, perform a Reversal request on the previous authorise transaction. The authorisation reference must be sent in the reference field.

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "webhookUrl": "https://shop/payhook?order=123456",
  "description": "Order 123456",
  "reference" : "C240305064258677CB87E192.G"
}' https://api.psp.ccv.eu/api/v1/reversal

    Example response

    {
  "lastUpdate": 1709621334602,
  "originalReference": "C240305064258677CB87E192.G",
  "created": 1709621334478,
  "brand": "visa",
  "description": "Order 123456",
  "status": "pending",
  "reference": "C240305064854420CB87E193.G",
  "merchantOrderReference": "123456",
  "method": "card",
  "type": "reversal",
  "language": "eng",
  "currency": "eur"
}

  2. At this point you don’t know whether the reversal is successful or not.

    • You must request the status of the reversal in order to complete your order correctly. See also Read a transaction.
    • You must not assume that a return of the customer is due to successful reversal!

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=C240305064854420CB87E193.G

    Example response

    {
  "originalReference": "C240305064258677CB87E192.G",
  "lastUpdate": 1709621334942,
  "statusFinalDate": 1709621334942,
  "methodTransactionId": "tMuzqg",
  "entryMode": "ecom",
  "created": 1709621334478,
  "details": {
    "initialTransactionId": "p3GNcBD4tLFo800",
    "acquirerResponseCode": "00",
    "authorisedAmount": 9.99,
    "acquirer": "Valitor",
    "acquirerResponseCodeDescription": "ApprovedOrCompletedSuccessfully"
  },
  "status": "success",
  "description": "Order 123456",
  "brand": "visa",
  "amount": 5.31,
  "merchantOrderReference": "123456",
  "notificationRequests": [],
  "reference": "C240305064854420CB87E193.G",
  "returnUrl": "https://shop/return?order=123456",
  "method": "card",
  "type": "capture",
  "language": "eng",
  "currency": "eur"
}

  3. After effect of completing a payment (successfully or not) we will notify you using a webhook. This allows you to perform additional operations in your system like sending an email to your customer.

Reverse Terminal Transactions

These details are possible when reversing an authorisation or sale which was made using the method terminal. Any details included in the original authorise or sale can be overwritten with these details.

Name Required Description Max Length
cardPresent No Specify whether the customer’s card has to be present to perform the reversal. Defaults to true.
terminalId No The terminal id as assigned by CCV 50
managementSystemId No The management system id of this terminal as assigned by CCV 50
accessProtocol No The communication protocol between the terminal and access server 20
ip No The browser accessible IP of the terminal for initiating the wake up 50
port No The browser accessible port of the terminal’s socket handling HTTP calls 5
operatingEnvironment Conditional Only ATTENDED terminal reversals are supported. Meaning it is required to include ATTENDED if the operatingEnvironment of the transaction being reversed was set to SEMI_UNATTENDED. 20
merchantLanguage No The language of the merchant, used to change the language in which the intermediate page is displayed in ATTENDED operatingEnvironments. Required when operatingEnvironment is ATTENDED, not required otherwise. 3

Example Request

{
  "webhookUrl": "https://shop/payhook?order=123456",
  "description": "Order 123456",
  "reference" : "C240305064258677CB87E192.G",
  "details": {
    "terminalId": "1234567",
    "managementSystemId": "1234567",
    "accessProtocol": "OPI_NL",
    "ip": "192.168.1.154",
    "port": "6235",
    "operatingEnvironment": "ATTENDED",
    "merchantLanguage": "ita"
  }
}

FAQ

Can I capture an authorisation multiple times?

Yes, depending on the payment method, you can capture an authorisation multiple times, as long as the total amount captured does not exceed the authorised amount.

Can I capture an authorisation partially?

Yes, you can capture an authorisation partially, as long as the total amount captured does not exceed the authorised amount.

Can I reverse an authorisation after I have captured it?

No, you cannot reverse an authorisation after you have captured it. You should refund the specific capture instead. See the Refund API for more information.

Can I reverse an authorisation multiple times?

No, you can only reverse an authorisation once, the full authorisation will be reversed.

How long is an authorisation valid?

The validity of an authorisation is specific to the payment method and can be found in the Payment Methods documentation.

Can I capture an authorisation after it has expired?

No, you cannot capture an authorisation after it has expired. You will need to authorise the payment again.

Can I reverse an authorisation after it has expired?

No, you cannot reverse an authorisation after it has expired. The authorisation will already be reversed automatically.

Can I capture an authorisation after I have reversed it?

No, you cannot capture an authorisation after you have reversed it. You will need to authorise the payment again.

What happens when an authorisation returns a lower authorised amount than requested?

When an authorisation returns a lower authorised amount than requested, you can either capture the lower amount or reverse the authorisation to release the reserved funds on the customer’s account. This is the amount that is reserved on the customer’s account. The authorisedAmount can be different from the requested amount, for example when a card has a limit on the maximum amount that can be authorised.

What happens when I try to capture the full amount of an authorisation, but the authorised amount is lower than the requested amount?

When you try to capture the full amount of an authorisation, but the authorised amount is lower than the requested amount, the capture will fail and return an error.

What happens when I try to capture an amount that exceeds the authorised amount?

When you try to capture an amount that exceeds the authorised amount, the capture will fail and return an error.

What happens when I capture an authorisation that has a lower amount than the request amount, and I do not specify a capture amount?

When you capture an authorisation that has a lower amount than the request amount, and you do not specify a capture amount, the capture will use the authorised amount as the default amount for the capture. Please note that the capture can still be successful, but the amount captured will be lower than the requested amount. You should always check the authorisedAmount in the transaction details to ensure that you are capturing the correct amount.

What do I need to do if I am not OK with the authorised amount?

If you are not OK with the authorised amount, you can reverse the authorisation to release the reserved funds on the customer’s account. You will need to initiate a reversal request for the authorisation transaction.