menu

Payment API

What's on this page

API Reference / Capture

Capture

An existing authorization can be captured using this resource.

Capture object

Name Description
type Fixed value: capture
amount The capture amount
currency Echo from the Payment
status Possible values: Transaction Status
paidout A boolean value that indicates if this transaction has been paid out. Only available for collecting Payments. Possible values: yes or no
paidoutDate The date on which the payment to the merchant was done. Only available for Collecting Payments
expectedPayoutTimestamp The date on which the payment to the merchant will be done. Only available for Collecting Payments
merchantOrderReference Echo from the Payment
description The description of the transaction
language Echo from the Payment
method Echo from the Payment
brand Echo from the Payment
metadata Echo from the Payment
reference A unique reference for the capture transaction
originalReference The unique reference for the payment transaction this payment is attempting to capture.
unstructuredReference The unstructured reference used when performing the payout to the merchant. Only available for Collecting Payments
paidoutReference The reference used when performing the payout to the merchant. This can be used to look up transactions related to that payout. Only available for Collecting Payments
created The local server datetime the capture was created, epoch timestamp
lastUpdate The local server datetime the capture was updated, epoch timestamp
statusFinalDate The local server datetime the capture reached a final status, epoch timestamp
failureCode An error code indication what caused the failure. Possible values: Failure Codes
payoutInstructions Optional list of Payout Instruction set by the capture initiator to indicate which merchants of the original payment were eligible for a capture. See Split Payout for more info.

Payout instruction Capture object

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.

Name Description
externalReference This is the reference to the sub merchant for this payout instruction.
amount The amount to withhold for pay out to the sub merchant.
paidout A boolean value that indicates that the payout instruction’s amount is withheld from a pay out to the sub merchant. Possible values: yes or no
paidoutDate An epoch timestamp of the payout to the sub merchant where this payout instruction is withheld from.
unstructuredReference The message used in the payout to the sub merchant.
structuredReference Custom structured reference used in the pay out.
paidoutReference The reference to the payout to the sub merchant.

Example

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00,
  "paidout" : "yes",
  "paidoutDate": 1605258439475,
  "unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 3 MREF. Lamp Shop",
  "paidoutReference": "579fd569"
}

Capture request

  • Resource: /api/v1/capture
  • Method: POST
  • Content-Type: application/json
  • Authentication: basic auth
  • Supports idempotency
  • Parameters
Name Required Description Max Length
reference Yes The unique reference of the payment to capture 255
description No The description of the capture. If not provided we use the original payment description 255
amount No The amount to capture. If not provided we use the original payment amount. The currency used will be the currency of the original payment and the format must be the same 12 digits in total, of which maximum 2 decimal digits
webhookUrl No The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url 2000
notificationRequests No An object which is used to request Notifications for specific events related to this capture. n/a
orderLines No Optional list of order lines that this capture includes (e.g. For a partial capture, only some of the orderlines are captured. Order Line n/a
deliveryInfo No Optional list containing one or more delivery information objects for this capture. Note: Currently only supported by payment method klarna. 500 delivery information objects
details No An object which includes method specific details. Possible values: Method Capture Details. n/a
merchantOrderReference No A reference, maximum of 255 characters, of the order associated with this capture. If not provided we use the merchantOrderReference of the original payment 255

Example

{
  "reference": "C1505181754007360.1",
  "description": "API Capture Description",
  "deliveryInfo": [
    {
      "shippingCompany" : "DHL EU",
      "trackingNumber" : "13456",
      "trackingUri" : "http://example/tracking/13456",
      "returnShippingCompany" : "DHL EU",
      "returnTrackingNumber" : "456789",
      "returnTrackingUri" : "http://example/tracking/456789"
    }
  ]
}

Method Capture Details

Terminal Capture Details

These details are possible when capturing a payment which was made using the method terminal. Any details included in the original authorise 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 capture. 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 No The environment in which the terminal is operating. Possible values: ATTENDED and SEMI_UNATTENDED. Defaults to SEMI_UNATTENDED when empty. Only ATTENDED is supported for payments of type authorise. 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

Payout Instruction Capture Request Details

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
Name Description
externalReference This is the reference to the merchant for this payout instruction. Present when the payment requires multiple payout instructions to identify different merchants.
amount The amount to be withheld for pay out to the referenced merchant.
structuredReference This is the structured reference to the merchant for this payout instruction. It is present when the payment requires multiple payout instructions to identify different merchants. The value must only contain numbers.
If you want to send +++090/9337/55493+++, then send 090933755493.

Example

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00,
  "structuredReference" : "090933755493"
}

Capture response

  • Status Code: 200
  • Content Type: application/json
  • Content: Capture

Example

{
  "type" : "capture",
  "amount" : 316.35,
  "currency" : "eur",
  "status" : "PENDING",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Capture Description",
  "language" : "eng",
  "method" : "card",
  "metadata" : "my custom metadata",
  "reference" : "C1505181613078800.1",
  "brand" : "visa",
  "created" : 1431958387914,
  "lastUpdate" : 1431958387914,
  "statusFinalDate" : 1431958387914
}