Create and update captures.
Capture is the process by which payments are secured once the payment has been authorized.
The Capture REST API captures a payment for the full or partial amount, or changes the capture date to today. A new capture record is created and the status of the existing capture is updated to CANCELED, if and only if the existing capture(s) don't have the status STARTED or CAPTURED.
By default, a capture for the full amount is created when the shopper authorizes the payment with a capture date of today. In this case, the capture call is only needed if a lower amount should be captured.
The default capture can be changed to a day in the future, or no default capture at all, by means of a configuration request. In the first case, the capture-request can be used to capture the payment earlier (today), or for a lower amount. In the latter case the capture call must be used, otherwise no money will be settled.
Note: Depending on the payment method the capture is already captured when authorized by the shopper, and has the status CAPTURED.
POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/payments/{payment_id}/captures
Identifiers
Name | Type | Description |
---|---|---|
merchant_key | MerchantKey | The key of the merchant. |
order_key | OrderKey | The key of the order. |
payment_id | PaymentIdentifier | The payment identifier. |
Parameters
Not applicable.
Request
Field | Type | M | Description |
---|---|---|---|
amount | Amount | O | The capture amount in minor units, e.g. in cents. |
currency | Currency | C | The capture amount currency. Must be present if the capture amount is given. |
item_lines | Block[] | O | A list of items with item code and quantity. |
+ code | String(1, 50) | M | The item code for an item. |
+ quantity | Number(1,2^30) | M | The quantity of an item. |
shipping_information | Block | O | The shipping and tracking information for the shipped item(s). |
+ shipping_company | String(1,100) | C | The company that has shipped the item(s). e.g. "DHL". Mandatory for the shipping methods "PICKUP_POINT", "POSTAL", "DHL_PACK_STATION". |
+ shipping_method | Enum(32) | M | The shipping method that is used to ship the item. |
+ tracking_number | String(1,100) | C | The tracking number to track the shipment. Required only when shipping company has been provided. |
+ tracking_uri | String(1,1024) | C | The URL where the shipment can be tracked by the shopper. Required only when shipping company has been provided. |
+ return_shipping_company | String(1,100) | C | The name of the company for the return shipment. Mandatory for the shipping methods "PICKUP_POINT", "POSTAL", "DHL_PACK_STATION". |
+ return_tracking_number | String(1,100) | C | The tracking number for the return shipment. Required only when return shipping company has been provided. |
+ return_tracking_uri | String(1,1024) | C | The URL where the shopper can track the return shipment. Required only when return shipping company has been provided. |
The fields amount
and currency
are calculated when item_lines
are provided. The request will be rejected, when
amount
, currency
, and item_lines
are provided.
The following shipping methods are supported:
Shipping Method | API Enum Value |
---|---|
Pickup Store | PICKUP_STORE |
Pickup Point | PICKUP_POINT |
Own | OWN |
Postal | POSTAL |
DHL Pack Station | DHL_PACK_STATION |
Digital | DIGITAL |
Undefined | UNDEFINED |
The shipping method UNDEFINED is only used for Klarna payment method.
Response
Not applicable.
HTTP Status
Status | Meaning |
---|---|
201 (Created) | The capture is successfully created. |
400 (Bad Request) | The request was not valid, or there was already a capture with the status STARTED or CAPTURED. |
401 (Unauthorized) | Authorization header missing or invalid. |
403 (Forbidden) | The merchant key is not allowed. |
Capture Payment example with amount and currency
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/94D261BBF80E4AC7212B127D3BD2E279/payments/pid1607033373t/captures \
-d '{
"amount" : 1000,
"currency" : "EUR",
}'
< Http 201 Created
Capture Payment example with itemLines and shippingInformation
> curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/94D261BBF80E4AC7212B127D3BD2E279/payments/pid1607033373t/captures \
-d '{
"item_lines" : [
{
"code" : "SDC4/4GB-2ADP",
"quantity" : 1
},
{
"code" : "9781741791570",
"quantity" : 2
}
],
"shipping_information" : {
"shipping_company" : "DHL",
"shipping_method" : "PICKUP_POINT",
"tracking_number" : "111",
"tracking_uri" : "trackingUri",
"return_shipping_company" : "DHL EU",
"return_tracking_number" : "222",
"return_tracking_uri" : "returnTrackingUri"
}
}'
< Http 201 Created