curl --request POST \
  --url https://api.sandbox.primer.io/payments/{id}/capture \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "amount": 42
}'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "SETTLED",
  "orderId": "order-abc",
  "customerId": "customer-123",
  "currencyCode": "EUR",
  "amount": 42,
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "descriptor": "Purchase: Socks",
    "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "411111",
      "firstDigits": "41111111",
      "last4Digits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cardholderName": "John Biggins",
      "network": "Visa",
      "isNetworkTokenized": false,
      "binData": {
        "network": "VISA",
        "regionalRestriction": "UNKNOWN",
        "accountNumberType": "UNKNOWN",
        "accountFundingType": "UNKNOWN",
        "prepaidReloadableIndicator": "NOT_APPLICABLE",
        "productUsageType": "UNKNOWN",
        "productCode": "VISA",
        "productName": "VISA"
      }
    }
  },
  "processor": {
    "name": "STRIPE",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 42,
    "amountRefunded": 0
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    }
  ],
  "customer": {
    "email": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

{
  "error": {
    "errorId": "PaymentError",
    "description": "The payment could not be found",
    "diagnosticsId": "1234567898"
  }
}

{
  "error": {
    "errorId": "PaymentRequestLimitExceeded",
    "description": "Payment has exceeded the maximum number of request attempts.",
    "recoverySuggestion": "This payment has many failed requests, which indicates the requests are invalid or the payment is in an unrecoverable state. Retrieve the payment or view it in the dashboard for more details.",
    "diagnosticsId": "1234567898"
  }
}

{
  "error": {
    "errorId": "RequestValidationError",
    "description": "We were unable to validate your request, please check your payload against /docs/api",
    "diagnosticsId": "1234567898",
    "validationErrors": [
      {
        "model": "PaymentCaptureAPIRequest",
        "errors": [
          {
            "path": "$.amount",
            "description": "Value must be a valid integer"
          }
        ]
      }
    ]
  }
}

Capture a payment

If you have successfully authorized a payment, you can now fully capture, or partially capture funds from the authorized payment, depending on whether your selected payment processor supports it. The payment will be updated to SETTLED or SETTLING, depending on the payment method type.

The payload sent in this capture request is completely optional. If you don’t send a payload with the capture request, the full amount that was authorized will be sent for capture. Below are the available payload attributes, which give you more granular control when capturing funds, if you require it.

Failed request limit: Primer limits how many failed requests a single payment can have. Failed capture, cancel, refund and adjust-authorization requests all count towards the same limit, which is currently 100 per payment. Once a payment reaches the limit, any further capture, cancel, refund or adjust-authorization request for that payment is rejected with a 409 and the error ID PaymentRequestLimitExceeded. The rejected request is not sent to the processor. Do not retry after this error: retrieve the payment to see why its previous requests failed, and contact Primer support if you need the payment unblocked.

POST

payments

{id}

capture

curl --request POST \
  --url https://api.sandbox.primer.io/payments/{id}/capture \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "amount": 42
}'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "SETTLED",
  "orderId": "order-abc",
  "customerId": "customer-123",
  "currencyCode": "EUR",
  "amount": 42,
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "descriptor": "Purchase: Socks",
    "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "411111",
      "firstDigits": "41111111",
      "last4Digits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cardholderName": "John Biggins",
      "network": "Visa",
      "isNetworkTokenized": false,
      "binData": {
        "network": "VISA",
        "regionalRestriction": "UNKNOWN",
        "accountNumberType": "UNKNOWN",
        "accountFundingType": "UNKNOWN",
        "prepaidReloadableIndicator": "NOT_APPLICABLE",
        "productUsageType": "UNKNOWN",
        "productCode": "VISA",
        "productName": "VISA"
      }
    }
  },
  "processor": {
    "name": "STRIPE",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 42,
    "amountRefunded": 0
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "SETTLED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    }
  ],
  "customer": {
    "email": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

{
  "error": {
    "errorId": "PaymentError",
    "description": "The payment could not be found",
    "diagnosticsId": "1234567898"
  }
}

{
  "error": {
    "errorId": "PaymentRequestLimitExceeded",
    "description": "Payment has exceeded the maximum number of request attempts.",
    "recoverySuggestion": "This payment has many failed requests, which indicates the requests are invalid or the payment is in an unrecoverable state. Retrieve the payment or view it in the dashboard for more details.",
    "diagnosticsId": "1234567898"
  }
}

{
  "error": {
    "errorId": "RequestValidationError",
    "description": "We were unable to validate your request, please check your payload against /docs/api",
    "diagnosticsId": "1234567898",
    "validationErrors": [
      {
        "model": "PaymentCaptureAPIRequest",
        "errors": [
          {
            "path": "$.amount",
            "description": "Value must be a valid integer"
          }
        ]
      }
    ]
  }
}

Authorizations

X-API-KEY

string

header

required

Headers

X-Idempotency-Key

string

Optional key to make the request idempotent. Enables a safe retry of a request without risking the user being charged or refunded multiple times. The idempotency key must be generated by the client and needs to be unique for every new request.

Path Parameters

string

required

ID of the payment to capture.

Required string length: 8 - 9

Pattern: ^[a-zA-Z0-9]{8,9}$

Body

application/json

amount

integer<int64>

The amount you would like to capture, in minor units. The currency used on authorization is assumed.

If no amount is specified it defaults to the full amount.

Required range: x >= 0

final

boolean

default:true

Indicates whether the capture request is the final capture request.

After a final capture, no subsequent captures are allowed.

order

Order · object

More information associated with the order.

Show child attributes

metadata

Payment Metadata · object

Additional payment metadata. This only takes effect if the payment was created via the New Workflows (read more here). A dictionary of key-value pairs where the values can only be strings or integers. Keys which already exist in the payment metadata will be overwritten.

Response

Successful Response

string

The unique payment ID.

You can use this ID to retrieve the payment details, or perform downstream operations.

date

string<date-time>

The date and time at which the payment was created in UTC format.

dateUpdated

string<date-time>

The date and time of the last payment update in UTC format.

status

enum<string>

See the payment status table for more information.

Available options:

PENDING,

FAILED,

AUTHORIZED,

SETTLING,

PARTIALLY_SETTLED,

SETTLED,

DECLINED,

CANCELLED

cardTokenType

enum<string>

The type of card token used for the payment.

Only applies for card payments.

Available options:

CARD_PAN,

NETWORK_TOKEN,

PROCESSOR_TOKEN

Example:

"CARD_PAN"

orderId

string

Your reference for the payment.

Maximum string length: 255

currencyCode

enum<string>

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BOV,

BRL,

BSD,

BTN,

BWP,

BYR,

BYN,

BZD,

CAD,

CDF,

CHE,

CHF,

CHW,

CLP,

CNY,

COP,

COU,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MKD,

MMK,

MNT,

MOP,

MUR,

MVR,

MWK,

MXN,

MXV,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLE,

SOS,

SRD,

SSP,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VED,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMW,

ZWG,

ZWL

amount

integer<int64>

The amount you charged the customer, in minor units.

Required range: x >= 0

order

Order Details · object

More information associated with the order.

Show child attributes

customerId

string

The unique identifier for your customer.

Maximum string length: 255

customer

Customer Details · object

More information associated with the customer.

Show child attributes

metadata

Payment Metadata · object

Additional data to be used throughout the payment lifecycle.

paymentMethod

Payment Method Options · object

The payment method options provided in the request, as well as the token used to process the payment.

Show child attributes

processor

Processor Information · object

More information associated with the payment processor, including the processor name.

Show child attributes

requiredAction

Required action · object

Required action to perform in order to resume the payment workflow. This can be requiring a 3DS check from the customer for instance.

Show child attributes

statusReason

Status Reason · object

Check this field for more information regarding the payment's status. This is especially useful when the status is DECLINED or FAILED.

Show child attributes

transactions

TransactionOverviewAPISchema · object[]

A list summarizing the transactions that occurred while processing the payment.

Note: a refund is a separate transaction and so will appear in this transactions list if a refund was performed.

Show child attributes

riskData

Risk Data · object

Risk data associated with this payment.

Show child attributes