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 the merchant wants to withdraw the money later on, they can send a capture request. If the merchant decides to not withdraw the money, they can send a reversal request to release the reserved money on the customers account.

Authorise the payment

This requires the payment method to support authorisations. You can view the supported payment methods here.

  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 perform an authentication. In case of card payments, we use 3-D Secure to verify the customers 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 should 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 should not imply 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=C170807154516317CB87E193.1

    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. As a side 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.