# Capture transaction Capture a previously authorized transaction Endpoint: POST /v2/transactions/{ratepay_transaction_id}/captures Version: version 2 Security: Bearer Authentication ## Path parameters: - `ratepay_transaction_id` (string, required) ID of transaction to capture. Get an overview of key identifiers used in payment API. ## Header parameters: - `Idempotency-Key` (string) ID generated by client to uniquely identify the request. It is highly recommended to use a UUID version 4. Do not reuse an idempotency key for different calls. See Idempotency for further details. - `Prefer` (string) According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource. Enum: "return=representation" - `X-Partner` (string) The partner ID for the operation is required only when using a single credential set for multiple integrations, such as countries or brands associated with one company. ## Request fields (application/json): - `gross_amount` (number, required) Amount to capture given in currency of original transaction. Example: 67.6 - `items` (array) List of captured items. - `items.article_number` (string) The article number of the item, e.g. SKU. Not allowed to contain only whitespaces. Example: "kitchen-utils-1" - `items.category` (string) Category for the item. Example: "household" - `items.description` (string) Description of the item. Example: "fruit knife with curved blade, 8 cm" - `items.gross_total_price` (number) Gross value including discount of these items after taxes. gross_total_price = (gross_unit_price + gross_unit_discount) * quantity Example: 33.8 - `items.gross_unit_discount` (number) Gross discount on one item after taxes. Needs to be a negative value. Example: -1.55 - `items.gross_unit_price` (number, required) Gross value of one item before taxes. For the RETURN_FEE type, applicable only to the REFUND operation, the value must be negative. Example: 18.45 - `items.name` (string, required) Name of the item. Example: "fruit knife" - `items.net_total_price` (number) Net value including discount of these items before taxes. net_total_price = (net_unit_price + net_unit_discount) * quantity Example: 28.4 - `items.net_unit_discount` (number) Net discount on one item before taxes. Needs to be a negative value. Example: -1.3 - `items.net_unit_price` (number) Net value of one item before taxes. Example: 15.5 - `items.quantity` (number, required) Ordered quantity of the item. Example: 2 - `items.tax_rate` (number, required) Tax rate applicable for the item given in percent. Example: 19 - `items.unit` (string) Arbitrary measurement unit of the item, e.g. kg, litre, pieces. Example: "piece" - `partner_invoice_id` (string) Arbitrary invoice ID generated by partner. Example: "partner-invoice-id-1234" - `partner_operation_id` (string) The unique ID generated by the partner or shop to identify an API operation. This ID can be displayed in settlement reports to allow relating settlement report items to API operations. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. Example: "capture-id-1234" - `partner_shop_id` (string) The shop ID provided upfront by Ratepay or generated by the partner in PSP (payment service providers) scenarios. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. This field is required in case of marketplace transaction. Example: "partner-shop-id-1" - `partner_transaction_id` (string, required) The transaction ID generated by the partner (i.e. Partner Order ID). Use the same value as shop_transaction_id unless the shop and integration partner manage separate transaction IDs, such as in PSP (payment service provider) integrations. This field must be included in at least one of the following requests: authorization or capture. This ID can be displayed in settlement reports. Get an [overview of key identifiers](/docs/developer/api_integration/payment_2.0/key_identifiers/) used in payment API. Example: "partner-transaction-id-1234" - `shop_transaction_id` (string, required) The transaction ID generated by the shop (i.e. Shop Order ID). Differs from partner_transaction_id only in PSP (payment service provider) scenarios. This field must be included in at least one of the following requests: authorization or capture. This ID must be known to the buyer and is used for buyer communication, e.g. correspondences and buyer support. Example: "shop-transaction-id-1234" - `special_items` (array) List of captured special items, e.g. shipping costs or discounts. Example: [{"article_number":"SHIPPING_001","category":"shipping","description":"Standard shipping via DHL","gross_total_price":5.95,"gross_unit_price":5.95,"name":"Shipping costs","net_total_price":5,"net_unit_price":5,"quantity":1,"tax_rate":19,"unit":"shipment"}] - `special_items.type` (string) The special item type the buyer selected. RETURN_FEE type is applicable only for the REFUND operation. Click [here](/docs/developer/api_integration/payment_2.0/example_requests/for_merchants/#With-items-and-buyer-return-fee) for example about usage for merchants or [here](/docs/developer/api_integration/payment_2.0/example_requests/for_marketplaces/#With-items-and-buyer-return-fee) for marketplaces. Enum: "RETURN_FEE" - `vats` (array) List of value-added tax (VAT) amounts. - `vats.net_amount` (number) The net amount before taxes for the given tax rate. Example: 56.81 - `vats.tax_amount` (number) The tax amount for the given tax rate. Example: 10.79 - `vats.tax_rate` (number) Tax rate given as percentage on the net amount. Example: 19 ## Response 400 fields (application/problem+json): - `decline` (object, required) Information about why transaction was not accepted and declined. - `decline.category` (string, required) Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details. Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" - `decline.invalid_fields` (array) List of one or multiple entries describing each failed validation. Only present if reason is INVALID_FIELDS. - `decline.invalid_fields.json_path` (string, required) The JSON path pointing to the location where the validation failed. Example: "partner_operation_id" - `decline.invalid_fields.message` (string, required) A message describing which constraint was violated. Example: "size must be between 0 and 255" - `decline.reasons` (array, required) List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category. Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED", "OTP_VERIFICATION_REQUIRED_BUT_FEATURE_NOT_ENABLED", "ORDER_WITH_PHONE_INTELLIGENCE_FRAUD_SUSPICION_BLOCKLISTED", "OTP_FAILED", "OTP_EXPIRED" ## Response 404 fields (application/problem+json): - `decline` (object, required) Information about why transaction was not accepted and declined. - `decline.category` (string, required) Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details. Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" - `decline.reasons` (array, required) List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category. Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ## Response 422 fields (application/problem+json): - `decline` (object, required) - `decline.category` (string, required) Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details. Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" - `decline.reasons` (array) List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category. Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ## Response 451 fields (application/problem+json): - `decline` (object, required) Information about why transaction was not accepted and declined. - `decline.category` (string, required) Decline category, see [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) for details. Enum: "BUYER_DATA", "BUYER_IDENTITY", "CONFLICT", "CONTRACT", "LEGAL", "PAYMENT_ATTRIBUTE", "RESOURCE_NOT_FOUND", "RISK_DECISION", "SYNTAX", "TRANSACTION_RISK", "UNPROCESSABLE_OPERATION" - `decline.reasons` (array, required) List of none, one or multiple reasons why the request was declined. See [Decline Categories](/docs/developer/api_integration/payment_2.0/declines/decline_categories/) to learn about possible reasons for each decline category. Enum: "INVALID_FIELDS", "INVALID_JSON", "INVALID_BILLING_ADDRESS", "INVALID_BILLING_ADDRESS_ZIP_CODE", "INVALID_DELIVERY_ADDRESS", "INVALID_DELIVERY_ADDRESS_ZIP_CODE", "CURRENCY_NOT_ALLOWED", "ANONYMIZED_BY_BUYER", "CANCELLATION_AMOUNT_TOO_HIGH", "CANCELLATION_NOT_FOUND", "CAPTURE_AMOUNT_TOO_HIGH", "CAPTURE_NOT_FOUND", "REFUND_NOT_FOUND", "AUTHORIZATION_NOT_FOUND", "NOT_ALLOWED_FOR_DECLINED_TRANSACTION", "REFUND_AMOUNT_TOO_HIGH", "TRANSACTION_NOT_FOUND", "WRONG_NUMBER_OF_SHOP_BASKETS", "WRONG_NUMBER_OF_SHOPS", "MULTIPLE_SHOP_BASKETS_WITH_SAME_SHOP_NOT_ALLOWED", "BASKET_WITH_UNKNOWN_SHOP", "BASKET_AMOUNT_TOO_LOW", "BASKET_AMOUNT_TOO_HIGH", "DELIVERY_COUNTRY_NOT_ALLOWED", "BILLING_COUNTRY_NOT_ALLOWED", "IDEMPOTENCY_KEY_ALREADY_USED", "DELIVERY_TYPE_NOT_ALLOWED", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_TRANSACTION_AMOUNT", "SUM_OF_ITEM_AMOUNTS_NOT_MATCHING_OPERATION_AMOUNT", "B2C_BUYER_NOT_ALLOWED", "B2B_BUYER_NOT_ALLOWED", "INVALID_PERSON_DATA", "SALES_CHANNEL_NOT_ALLOWED", "INVALID_IBAN", "PAYMENT_METHOD_NOT_ALLOWED", "SHOP_CREATION_NOT_ALLOWED", "MAXIMUM_EXPIRY_EXCEEDED", "NOT_ALLOWED_FOR_EXPIRED_TRANSACTION", "MULTIPLE_VAT_OBJECTS_PER_TAX_RATE_NOT_ALLOWED", "MULTIPLE_RETURN_FEES_NOT_ALLOWED", "RETURN_FEE_NOT_ALLOWED", "PARTNER_SHOP_ID_MUST_BE_GIVEN_FOR_MARKETPLACE_TRANSACTIONS", "DEVIATING_DELIVERY_ADDRESS_B2C_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2C_IN_STORE_COLLECT_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_REGULAR_ADDRESS_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_BOX_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_PICK_UP_SHOP_NOT_ALLOWED", "DEVIATING_DELIVERY_ADDRESS_B2B_IN_STORE_COLLECT_NOT_ALLOWED" ## Response 500 fields