Skip to content
Developer
/
/
/Capture

Payment OpenAPI Specification (version 2)

This is the documentation for the Ratepay Payment API v2. The API is still in development and subject to change. The documentation will evolve as the development of the API progresses.

Download OpenAPI description
payment_api.json
payment_api.yaml
Overview
URL

https://www.ratepay.com/

Ratepay

info@ratepay.com

Languages
Servers
Ratepay Integration Platform

https://api-integration.ratepay.com/transaction/management/

Ratepay Production Platform

https://api.ratepay.com/transaction/management/

Transaction management

Operations

Incremental authorization

Operations

Cancellation

Operations

Capture

Operations

Retrieve all captures

Request

Retrieve all capture resources of an existing transaction including their attributes.

Security
Bearer Authentication
Path
ratepay_transaction_idstringrequired

ID of transaction to retrieve. Get an overview of key identifiers used in payment API.

Headers
Preferstring

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.

Value"return=representation"
X-Partnerstring

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.

curl -i -X GET \
  'https://api-integration.ratepay.com/transaction/management/v2/transactions/{ratepay_transaction_id}/captures' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Prefer: return=representation' \
  -H 'X-Partner: string'

Responses

Captures retrieved

Bodyapplication/hal+json
One of:

Includes only minimal set of attributes generated by Ratepay.

_embeddedobject
_linksobject(TransactionLinks)required

Links related to the resource following specification by IANA.

_links.​selfobject(TransactionSelfLink)required

The self relation identifying the transaction resource itself.

_links.​self.​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp"
ratepay_transaction_idstring[ 20 .. 127 ] characters[A-Za-z0-9-_]{20,127}required

ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions. Get an overview of key identifiers used in payment API.

Example: "scwBgARW-nE93I7_ywhp"
Response
application/hal+json
{
  "_embedded": {
    "captures": [ … ]
  },
  "_links": {
    "self": { … }
  },
  "ratepay_transaction_id": "scwBgARW-nE93I7_ywhp"
}

Capture transaction

Request

Capture a previously authorized transaction

Security
Bearer Authentication
Path
ratepay_transaction_idstringrequired

ID of transaction to capture. Get an overview of key identifiers used in payment API.

Headers
Idempotency-Keystring<= 64 characters

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.

Preferstring

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.

Value"return=representation"
X-Partnerstring

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.

Bodyapplication/jsonrequired
gross_amountnumberdecimal places <= 2> 0required

Amount to capture given in currency of original transaction.

Example: 67.6
itemsArray of objects(ItemDto)

List of captured items.

partner_invoice_idstring[ 0 .. 50 ] characters

Arbitrary invoice ID generated by partner.

Example: "partner-invoice-id-1234"
partner_operation_idstring[ 0 .. 255 ] characters

Arbitrary ID of partner for the operation. This ID can be displayed in settlement reports. Get an overview of key identifiers used in payment API.

Example: "capture-id-1234"
partner_shop_idstring[ 1 .. 255 ] characters

The shop ID generated by the partner or provided upfront by Ratepay. Get an overview of key identifiers used in payment API. This field is required in case of marketplace transaction.

Example: "partner-shop-id-1"
partner_transaction_idstring[ 1 .. 50 ] charactersrequired

The transaction ID generated by the partner. 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 used in payment API.

Example: "partner-transaction-id-1234"
shop_transaction_idstring[ 1 .. 127 ] charactersrequired

The transaction ID generated by the shop. 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_itemsArray of objects(SpecialItemDto)

List of captured special items, e.g. shipping costs or discounts.

vatsArray of objects(VatDto)

List of value-added tax (VAT) amounts.

curl -i -X POST \
  'https://api-integration.ratepay.com/transaction/management/v2/transactions/{ratepay_transaction_id}/captures' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Prefer: return=representation' \
  -H 'X-Partner: string' \
  -d '{
    "gross_amount": 67.6,
    "items": [
      {
        "article_number": "kitchen-utils-1",
        "category": "household",
        "description": "fruit knife with curved blade, 8 cm",
        "gross_total_price": 33.8,
        "gross_unit_discount": -1.55,
        "gross_unit_price": 18.45,
        "name": "fruit knife",
        "net_total_price": 28.4,
        "net_unit_discount": -1.3,
        "net_unit_price": 15.5,
        "quantity": 2,
        "tax_rate": 19,
        "unit": "piece"
      }
    ],
    "partner_invoice_id": "partner-invoice-id-1234",
    "partner_operation_id": "capture-id-1234",
    "partner_shop_id": "partner-shop-id-1",
    "partner_transaction_id": "partner-transaction-id-1234",
    "shop_transaction_id": "shop-transaction-id-1234",
    "special_items": [
      {
        "article_number": "kitchen-utils-1",
        "category": "household",
        "description": "fruit knife with curved blade, 8 cm",
        "gross_total_price": 33.8,
        "gross_unit_discount": -1.55,
        "gross_unit_price": 18.45,
        "name": "fruit knife",
        "net_total_price": 28.4,
        "net_unit_discount": -1.3,
        "net_unit_price": 15.5,
        "quantity": 2,
        "tax_rate": 19,
        "type": "RETURN_FEE",
        "unit": "piece"
      }
    ],
    "vats": [
      {
        "net_amount": 56.81,
        "tax_amount": 10.79,
        "tax_rate": 19
      }
    ]
  }'

Responses

Capture created

Bodyapplication/hal+json
One of:

Includes only minimal set of attributes generated by Ratepay during capture creation.

_linksobject(CaptureLinks)required

Links related to the resource following specification by IANA.

_links.​selfobject(CaptureSelfLink)required

The self relation identifying the capture resource itself.

_links.​self.​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN"
createdstring(date-time)required

Timestamp with offset according to ISO 8601.

ratepay_capture_idstring[ 20 .. 127 ] characters[A-Za-z0-9-_]{20,127}required

ID of confirmed capture (generated by Ratepay). Get an overview of key identifiers used in payment API.

Example: "BFNpWnim6LUDFQA8x3VN"
Response
application/hal+json
{
  "_links": {
    "self": { … }
  },
  "created": "2019-08-24T14:15:22Z",
  "ratepay_capture_id": "BFNpWnim6LUDFQA8x3VN"
}

Retrieve a capture

Request

Retrieve a capture resource of an existing transaction including its attributes.

Security
Bearer Authentication
Path
ratepay_transaction_idstringrequired

ID of transaction to retrieve. Get an overview of key identifiers used in payment API.

ratepay_capture_idstringrequired

ID of capture to retrieve. Get an overview of key identifiers used in payment API.

Headers
Preferstring

According to RFC 7240: Provide return=representation if you prefer that the response to a request includes the current state of the resource.

Value"return=representation"
X-Partnerstring

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.

curl -i -X GET \
  'https://api-integration.ratepay.com/transaction/management/v2/transactions/{ratepay_transaction_id}/captures/{ratepay_capture_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Prefer: return=representation' \
  -H 'X-Partner: string'

Responses

Capture retrieved

Bodyapplication/hal+json
One of:

Includes only minimal set of attributes generated by Ratepay during capture creation.

_linksobject(CaptureLinks)required

Links related to the resource following specification by IANA.

_links.​selfobject(CaptureSelfLink)required

The self relation identifying the capture resource itself.

_links.​self.​hrefstringrequired

URI pointing to resource itself.

Example: "https://api-integration.ratepay.com/transaction/management/v2/transactions/scwBgARW-nE93I7_ywhp/captures/BFNpWnim6LUDFQA8x3VN"
createdstring(date-time)required

Timestamp with offset according to ISO 8601.

ratepay_capture_idstring[ 20 .. 127 ] characters[A-Za-z0-9-_]{20,127}required

ID of confirmed capture (generated by Ratepay). Get an overview of key identifiers used in payment API.

Example: "BFNpWnim6LUDFQA8x3VN"
Response
application/hal+json
{
  "_links": {
    "self": { … }
  },
  "created": "2019-08-24T14:15:22Z",
  "ratepay_capture_id": "BFNpWnim6LUDFQA8x3VN"
}

Shipping information

Operations

Refund

Operations