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.

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.

  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.

Reversal

  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.

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.