> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Refund a payment
>
Issue a full or partial refund for a previously settled payment. By default, the full amount
will be refunded unless a specific amount is provided for a partial refund.
If the payment was partially captured multiple times, you can specify which capture to
refund by using the transaction event ID. Refer to the `transactions.events` array in the
payment object to find available transaction event IDs (when the appropriate `expand`
parameter is passed).
When specifying a transaction event ID, the refund amount should not exceed the amount
captured in that event. If no refund amount is provided, it defaults to the amount captured
in that specific event.
## OpenAPI
````yaml https://api.schemas.primer.io/api-reference/v2.4/openapi.yaml post /payments/{id}/refund
openapi: 3.0.2
info:
x-logo:
url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
title: Primer API
version: '2.4'
description: >-
This API enforces a timeout of 90 seconds for all requests. A 504 response
indicates a timeout has occurred.
servers:
- url: https://api.sandbox.primer.io
- url: https://api.primer.io
security:
- ApiKeyAuth: []
tags:
- name: Client Session API
- name: Payments API
- name: Payment Methods API
- name: Payment Attempts API
paths:
/payments/{id}/refund:
post:
tags:
- Payments API
summary: Refund a payment
description: >
Issue a full or partial refund for a previously settled payment. By
default, the full amount
will be refunded unless a specific amount is provided for a partial
refund.
If the payment was partially captured multiple times, you can specify
which capture to
refund by using the transaction event ID. Refer to the
`transactions.events` array in the
payment object to find available transaction event IDs (when the
appropriate `expand`
parameter is passed).
When specifying a transaction event ID, the refund amount should not
exceed the amount
captured in that event. If no refund amount is provided, it defaults to
the amount captured
in that specific event.
operationId: refund_payment_payments__id__refund_post
parameters:
- required: true
schema:
title: Payment ID
type: string
name: id
description: ID of payment to refund.
in: path
- $ref: '#/components/parameters/IdempotencyHeader'
- $ref: '#/components/parameters/ApiVersionHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRefundAPIRequest'
title: Data
default: {}
examples:
Full Refund:
value: {}
Partial Refund:
value:
amount: 42
Partial Refund with Transaction Event:
value:
transactionEventId: 493cde19-04f2-4913-b00b-71af806f4374
Using Expand:
value:
expand:
- transactions.events
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentAPIResponse'
example:
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'
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: 42
transactions:
- type: SALE
processorStatus: SETTLED
processorName: STRIPE
processorMerchantId: acct_stripe_1234
processorTransactionId: 54c4eb5b3ef8a
cardTokenType: CARD_PAN
- type: REFUND
processorStatus: SETTLED
processorName: STRIPE
processorMerchantId: acct_stripe_1234
processorTransactionId: 54c4eb5b3ef8a
reason: 'Customer returned order #1234.'
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
'400':
description: Error Response
content:
application/json:
schema:
$ref: '#/components/schemas/400ErrorResponse'
example:
error:
errorId: PaymentError
description: The payment could not be found
diagnosticsId: '1234567898'
'409':
description: Error Response
content:
application/json:
schema:
$ref: '#/components/schemas/409ErrorResponse'
examples:
IdempotencyKeyAlreadyExists:
summary: Idempotency key already exists
value:
error:
errorId: IdempotencyKeyAlreadyExists
description: >-
The idempotency key "1234567898" already exists for
transaction
diagnosticsId: '1234567898'
paymentId: gg3r3tsa3
paymentStatus: SETTLED
PaymentAlreadyRefunded:
summary: Payment already refunded
value:
error:
errorId: PaymentAlreadyRefunded
description: >-
Cannot refund this payment because the payment has
already been fully refunded.
diagnosticsId: '1234567898'
'422':
description: Error Response
content:
application/json:
schema:
$ref: '#/components/schemas/422ErrorResponse'
examples:
RequestValidationError:
summary: Request validation error
value:
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
UnprocessableRefundAmount:
summary: Unprocessable refund amount
value:
error:
errorId: UnprocessableRefundAmount
description: >-
Cannot refund this payment with the amount 4201. The
refund amount must be less than or equal to the payment
authorized amount (4200).
diagnosticsId: '1234567898'
components:
parameters:
IdempotencyHeader:
required: false
schema:
title: X-Idempotency-Key
type: string
name: X-Idempotency-Key
description: >-
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.
in: header
ApiVersionHeader:
required: true
schema:
title: X-API-VERSION
type: string
example: '2.4'
name: X-API-VERSION
description: Specifies the version of the API to use. This must be set to `2.4`.
in: header
schemas:
PaymentRefundAPIRequest:
title: PaymentRefundAPIRequest
type: object
properties:
amount:
title: Amount to refund
minimum: 0
type: integer
format: int64
description: >-
The amount you would like to refund the customer, in minor units.
e.g. for $7, use `700`.
Defaults to remaining non-refunded amount.
orderId:
title: Order ID
type: string
description: >-
Optionally you can pass a specific order ID for the refund.
By default this will be set to the original `orderId` given on
payment creation.
reason:
title: Refund reason
type: string
description: >-
You can optionally specify a reason for the refund, for your own
records. This will be returned in the refund transaction of payment
responses.
transactionEventId:
title: Transaction Event ID
type: string
format: uuid
description: >-
Specific capture ID to target for the refund. Use this to specify
which transaction event the refund should apply to.
example: 57a2027d-36a6-494f-ad07-a6e1d0c77772
expand:
$ref: '#/components/schemas/Expand'
additionalProperties: false
example:
amount: 42
orderId: order-1234-refund
reason: 'Customer returned order #1234.'
PaymentAPIResponse:
title: PaymentAPIResponse
required:
- id
- date
- dateUpdated
- status
- orderId
- currencyCode
- amount
- paymentMethod
- transactions
type: object
properties:
id:
title: Payment identifier
type: string
description: >
The unique payment ID.
You can use this ID to retrieve the payment details, or perform
downstream
operations.
date:
title: Payment date
type: string
description: The date and time at which the payment was created in UTC format.
format: date-time
dateUpdated:
title: Payment updated date
type: string
description: The date and time of the last payment update in UTC format.
format: date-time
status:
$ref: '#/components/schemas/PaymentStatus'
title: Current status
description: >-
See the payment [status table](../docs#payment-status) for more
information.
cardTokenType:
title: Card token type used
allOf:
- $ref: '#/components/schemas/CardTokenTypeEnum'
description: |
The type of card token used for the payment.
Only applies for card payments.
example: CARD_PAN
orderId:
title: Order ID
type: string
description: Your reference for the payment.
maxLength: 255
currencyCode:
$ref: '#/components/schemas/Currency'
title: Currency
description: >
The 3-letter currency code in [ISO 4217
format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g.
use `USD` for US dollars.
amount:
title: Payment amount
minimum: 0
type: integer
format: int64
description: The amount you charged the customer, in minor units.
order:
$ref: '#/components/schemas/OrderDetailsAPISchema'
title: Order Details
description: More information associated with the order.
customerId:
title: The ID of the customer using the checkout
type: string
description: The unique identifier for your customer.
maxLength: 255
customer:
$ref: '#/components/schemas/CustomerDetailsAPISchema'
title: Customer Details
description: More information associated with the customer.
metadata:
title: Payment Metadata
type: object
description: |
Additional data to be used throughout the payment lifecycle.
paymentMethod:
$ref: '#/components/schemas/PaymentResponsePaymentMethodOptionsAPISchema'
title: Payment Method Options
description: >-
The payment method options provided in the request, as well as the
token used to process the payment.
processor:
$ref: '#/components/schemas/PaymentResponseProcessorAPISchema'
title: Processor Information
description: >-
More information associated with the payment processor, including
the processor name.
requiredAction:
$ref: '#/components/schemas/PaymentRequiredActionAPISchema'
title: Required action
description: >-
Required action to perform in order to resume the payment workflow.
This can be requiring a 3DS check from the customer for instance.
statusReason:
$ref: '#/components/schemas/StatusReasonAPISchema'
title: Status Reason
description: >
Check this field for more information regarding the payment's
status. This is especially useful when the status is `DECLINED` or
`FAILED`.
transactions:
title: Transactions
type: array
items:
$ref: '#/components/schemas/TransactionOverviewAPISchema'
description: >-
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.
riskData:
$ref: '#/components/schemas/RiskDataAPISchema'
title: Risk Data
400ErrorResponse:
title: 400ErrorResponse
type: object
required:
- error
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
- type: object
properties:
paymentId:
title: Payment ID
type: string
description: Payment ID of the related pay
paymentStatus:
title: Status
type: string
description: Status of the related payment
409ErrorResponse:
title: 409ErrorResponse
type: object
required:
- error
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
- type: object
properties:
paymentId:
title: Payment ID
type: string
description: Payment ID of the related payment
paymentStatus:
title: Status
type: string
description: Status of the related payment
422ErrorResponse:
title: 422ErrorResponse
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
Expand:
type: array
nullable: true
items:
type: string
enum:
- transactions.events
example:
- transactions.events
description: A list of fields to expand, such as transactions.events.
PaymentStatus:
title: PaymentStatus
enum:
- PENDING
- FAILED
- AUTHORIZED
- SETTLING
- PARTIALLY_SETTLED
- SETTLED
- DECLINED
- CANCELLED
type: string
description: An enumeration.
CardTokenTypeEnum:
title: CardTokenTypeEnum
enum:
- CARD_PAN
- NETWORK_TOKEN
- PROCESSOR_TOKEN
type: string
description: An enumeration.
Currency:
title: Currency
enum:
- 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
- MRO
- 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
- SOS
- SRD
- SSP
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XDR
- XFU
- XOF
- XPD
- XPF
- XPT
- XSU
- XTS
- XUA
- YER
- ZAR
- ZMW
- ZWL
description: >
3-letter currency code in ISO 4217
format,
e.g. USD for US dollars.
OrderDetailsAPISchema:
title: OrderDetailsAPISchema
type: object
properties:
lineItems:
title: Line Items
type: array
items:
$ref: '#/components/schemas/OrderLineItemsAPISchema'
description: The details of the line items of the order.
countryCode:
$ref: '#/components/schemas/CountryCodeEnum'
title: Country Code
description: The country in which the order is created
retailerCountryCode:
$ref: '#/components/schemas/CountryCodeEnum'
title: Retailer Country Code
description: The country code of the retailer
fees:
title: Fee Details
type: array
items:
$ref: '#/components/schemas/OrderFeesAPISchema'
description: The details of fees charged.
shipping:
$ref: '#/components/schemas/OrderShippingAPISchema'
title: Shipping Details
description: The details of shipping charged.
CustomerDetailsAPISchema:
title: CustomerDetailsAPISchema
type: object
properties:
emailAddress:
title: Email Address
type: string
description: >
Customer email address.
Note: It is recommended to include this field if a 3DS check will be
performed
format: email
mobileNumber:
title: Mobile Number
type: string
description: The customer's mobile number
maxLength: 255
firstName:
title: First Name
type: string
description: The customer's first name
maxLength: 255
lastName:
title: Last Name
type: string
description: The customer's last name
maxLength: 255
billingAddress:
$ref: '#/components/schemas/OptionalAddressAPISchema'
title: Billing Address
description: >
Customer billing address.
Note: It is recommended to include this field if a 3DS check will be
performed
shippingAddress:
$ref: '#/components/schemas/OptionalAddressAPISchema'
title: Shipping Address
description: Customer shipping address
taxId:
title: Tax ID
type: string
description: The customer's tax id number for tax exemptions
maxLength: 255
nationalDocumentId:
title: National Document ID
type: string
description: The customer's national identification number
maxLength: 255
PaymentResponsePaymentMethodOptionsAPISchema:
title: PaymentResponsePaymentMethodOptionsAPISchema
type: object
required:
- paymentMethodToken
- analyticsId
- paymentMethodType
- paymentMethodData
properties:
descriptor:
title: Payment descriptor
type: string
description: |
The description of the payment, as it would typically appear
on a bank statement.
maxLength: 255
paymentType:
$ref: '#/components/schemas/RecurringPaymentTypeSchema'
paymentMethodToken:
title: Payment method token
type: string
description: The payment method token used to authorize the transaction.
isVaulted:
title: Is Vaulted flag
type: boolean
description: >-
Whether the payment method token represents a vaulted payment method
and can be used for future payments.
default: false
analyticsId:
title: Unique analytics ID
type: string
description: Unique analytics identifier corresponding to a payment method
maxLength: 255
paymentMethodType:
$ref: '#/components/schemas/PaymentMethodTypeEnum'
title: Payment method type
description: Payment method type used for payment authorization.
paymentMethodData:
title: Payment method data
anyOf:
- $ref: '#/components/schemas/PaymentCardTokenAPISchema'
- $ref: '#/components/schemas/PayPalOrderTokenAPISchema'
- $ref: '#/components/schemas/PayPalBillingAgreementAPISchema'
- $ref: '#/components/schemas/GoCardlessMandateAPISchema'
- $ref: '#/components/schemas/KlarnaPaymentSessionAPISchema'
- $ref: '#/components/schemas/KlarnaCustomerTokenAPISchema'
- $ref: '#/components/schemas/IdealPayNLTokenAPISchema'
- $ref: '#/components/schemas/ApayaCustomerTokenAPISchema'
description: Payment method data
threeDSecureAuthentication:
$ref: '#/components/schemas/ThreeDSecureAuthenticationAPISchema'
title: Threedsecureauthentication
default:
responseCode: NOT_PERFORMED
authorizationType:
$ref: '#/components/schemas/AuthorizationTypeEnum'
title: Authorization Type
description: >-
Allows to adjust the authorized amount after the authorization, if
supported by payment method. `FINAL` - the authorized amount is
final and can not be adjusted. Adjusting the amount can be only done
via canceling the payment and re-authorization with new amount.
`ESTIMATED` - the amount can be adjusted after the authorization, if
supported by payment method.
PaymentResponseProcessorAPISchema:
title: PaymentResponseProcessorAPISchema
type: object
required:
- amountCaptured
- amountRefunded
properties:
name:
title: Processor Name
type: string
description: The payment processor used for this payment.
maxLength: 255
processorMerchantId:
title: Processor Merchant ID
type: string
description: >-
The merchant ID registered at the payment processor used for this
payment.
maxLength: 255
amountCaptured:
title: Amount captured
type: integer
minimum: 0
format: int64
description: >
If no capture was performed, this value will be set to `0`.
If one or more partial captures were performed, this value will be a
sum
of all partial capture amounts.
amountRefunded:
title: Amount refunded
type: integer
minimum: 0
format: int64
description: >
If no refund was performed, this value will be set to `0`.
If one or more partial refunds were performed, this value will be a
sum
of all partial refund amounts.
PaymentRequiredActionAPISchema:
title: PaymentRequiredActionAPISchema
required:
- name
- description
type: object
properties:
name:
$ref: '#/components/schemas/BlockingPaymentActionTypeEnum'
title: Name
description: Action name
description:
title: Description
type: string
description: Human description of the required action to perform.
clientToken:
title: Client token
type: string
description: >-
The client token to be returned to the SDK if a required action is
returned.
StatusReasonAPISchema:
title: StatusReasonAPISchema
required:
- type
type: object
properties:
type:
$ref: '#/components/schemas/PaymentStatusTypeEnum'
title: Payment status type
declineType:
$ref: '#/components/schemas/DeclineTypeEnum'
title: Decline Type
description: |
If the error is of type `ISSUER_DECLINED` this will be returned.
Declines of type `SOFT_DECLINE` may be retried,
whereas declines of type `HARD_DECLINE` should not be retried.
code:
$ref: '#/components/schemas/TransactionDeclineReasonV2Enum'
title: Payment status code
description: If the error is of type `ISSUER_DECLINED`, this will be returned.
message:
title: Processor message
type: string
description: >-
In case of an error on the processor's part, we will return the
message returned by the processor. This is usually a human readable
error.
paymentMethodResultCode:
title: Payment Method Result Code
type: string
description: >
The result code returned by the payment method or card network. This
code is unified across all supported processors.
_e.g. Code `46` refers to the message "Closed account" for Visa
across all supported processors._
paymentMethodResultMessage:
title: Payment Method Result Message
type: string
description: >
Human-readable version of the Payment Method Result Code. This
message is unified across all supported processors.
_e.g. Code `46` refers to the message "Closed account" for Visa
across all supported processors._
paymentMethodAdviceCode:
title: Payment Method Advice Code
type: string
description: >
The advice code returned by the payment method or card network. This
code is unified across all supported processors.
_For payments made with Mastercard, this represents the Merchant
Advice Code (MAC)._
_e.g. Code `24` refers to the message "Retry after 1 hour" for
Mastercard across all supported processors._
paymentMethodAdviceMessage:
title: Payment Method Advice Message
type: string
description: >
Human-readable version of the Payment Method Advice Code. This
message is unified across all supported processors.
_For payments made with Mastercard, this represents the message of
the Merchant Advice Code (MAC)._
_e.g. Code `24` refers to the message "Retry after 1 hour" for
Mastercard across all supported processors._
advisedAction:
$ref: '#/components/schemas/AdvisedActionEnum'
title: Advised Action
TransactionOverviewAPISchema:
title: TransactionOverviewAPISchema
required:
- date
- amount
- currencyCode
- orderId
- transactionType
- processorName
- processorMerchantId
- processorStatus
type: object
properties:
date:
title: Creation date
type: string
description: Date & time of the transaction (UTC)
amount:
minimum: 0
type: integer
format: int64
description: Transaction amount in minor units
currencyCode:
$ref: '#/components/schemas/Currency'
title: Currency
description: >
The 3-letter currency code in [ISO 4217
format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). e.g.
use `USD` for US dollars.
orderId:
title: Order ID
type: string
description: The reference submitted on payment creation or refund.
transactionType:
$ref: '#/components/schemas/TransactionTypeEnum'
title: Transaction type
processorTransactionId:
title: Processor's transaction ID
type: string
description: Processor's unique identifier for the transaction
processorName:
title: Processor Name
type: string
description: An identifier of a processor.
processorMerchantId:
title: Processor master account identifier
type: string
description: |
Processor's main account identifier.
* Adyen: Account code
* Braintree: Merchant ID
* Stripe: Account ID"
processorStatus:
$ref: '#/components/schemas/PaymentStatus'
title: Processor Transaction status
description: >-
Transaction status, please refer to the [Transaction Status
Codes](#section/API-Usage-Guide/Payment-Status) table for more
information
processorStatusReason:
$ref: '#/components/schemas/StatusReasonAPISchema'
title: Payment error
description: |
If the transaction has a declined or failed status.
Only if the status is `DECLINED` or `FAILED`, otherwise `null`.
cardTokenType:
title: Card token type used
allOf:
- $ref: '#/components/schemas/CardTokenTypeEnum'
description: |
The type of card token used for the payment.
Only applies for card payments.
example: CARD_PAN
reason:
title: Reason
type: string
description: >
The reason for a cancel or refund request on this transaction, if
any.
example: Item returned.
events:
title: Events
type: array
description: >-
A list of events related to the transaction, included when the
`expand` parameter is passed.
items:
$ref: '#/components/schemas/TransactionEventApiResponse'
RiskDataAPISchema:
title: RiskDataAPISchema
description: |
Risk data associated with this payment.
type: object
properties:
fraudChecks:
$ref: '#/components/schemas/FraudCheckAPISchema'
title: Fraud Checks
cvvCheck:
$ref: '#/components/schemas/CVVCheckAPISchema'
title: CVV Check
avsCheck:
$ref: '#/components/schemas/AVSCheckAPISchema'
title: AVS Check
ErrorObject:
title: Error
type: object
description: An object containing information about the error that occurred.
required:
- errorId
- description
properties:
errorId:
title: Error ID
type: string
description: An error ID
description:
title: Error description
type: string
description: A human readable description of the error
recoverySuggestion:
title: Recovery Suggestion
type: string
description: A suggestion on how to recover from the error.
diagnosticsId:
title: Error diagnostics ID
type: string
description: >-
An ID that you can quote when contacting the Primer support team via
our [Support
Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
validationErrors:
title: Validation Errors
type: array
items:
type: object
description: Returned in case of a badly formed request
OrderLineItemsAPISchema:
title: OrderLineItemsAPISchema
description: |
The details of the line items of the order.
The total amount of a line item is calculated like so:
````
totalAmount = (amount * quantity) - discountAmount + taxAmount
```
type: object
required:
- amount
properties:
itemId:
title: Item ID
type: string
description: A unique identifier for the line item.
minLength: 1
maxLength: 255
name:
title: Name
type: string
description: A name of the item.
maxLength: 255
description:
title: Item ID
type: string
description: A description of the item.
maxLength: 255
amount:
minimum: 0
type: integer
format: int64
description: >-
The amount charged to the customer, in minor units. The minimum
amount is 0. The maximum amount is the limit of `int64`.
quantity:
type: integer
description: The number of the particular line item that is being ordered.
default: 1
format: int64
discountAmount:
title: Discount Amount
minimum: 0
type: integer
format: int64
description: >-
Any discount applicable to this item, in minor units. This discount
is applied for the entire line item, and not per `quantity`.
taxAmount:
title: Tax Amount
minimum: 0
type: integer
format: int64
description: >-
The tax charged on this item, in minor units. This tax amount is
applied for the entire line item, and not per `quantity`.
taxCode:
title: Tax Code
type: string
description: >-
The tax code associated with this item, in minor units. This is
required for Primer-initiated tax calculations.
minLength: 1
maxLength: 255
productType:
$ref: '#/components/schemas/ProductTypeEnum'
title: Product Type
description: An identifier for the product type.
productData:
$ref: '#/components/schemas/OrderLineItemsProductDataAPISchema'
title: Product Data
description: Details related to the product
CountryCodeEnum:
title: CountryCodeEnum
enum:
- AW
- AF
- AO
- AI
- AX
- AL
- AD
- AE
- AR
- AM
- AS
- AQ
- TF
- AG
- AU
- AT
- AZ
- BI
- BE
- BJ
- BQ
- BF
- BD
- BG
- BH
- BS
- BA
- BL
- BY
- BZ
- BM
- BO
- BR
- BB
- BN
- BT
- BV
- BW
- CF
- CA
- CC
- CH
- CL
- CN
- CI
- CM
- CD
- CG
- CK
- CO
- KM
- CV
- CR
- CU
- CW
- CX
- KY
- CY
- CZ
- DE
- DJ
- DM
- DK
- DO
- DZ
- EC
- EG
- ER
- EH
- ES
- EE
- ET
- FI
- FJ
- FK
- FR
- FO
- FM
- GA
- GB
- GE
- GG
- GH
- GI
- GN
- GP
- GM
- GW
- GQ
- GR
- GD
- GL
- GT
- GF
- GU
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IM
- IN
- IO
- IE
- IR
- IQ
- IS
- IL
- IT
- JM
- JE
- JO
- JP
- KZ
- KE
- KG
- KH
- KI
- KN
- KR
- KW
- LA
- LB
- LR
- LY
- LC
- LI
- LK
- LS
- LT
- LU
- LV
- MO
- MF
- MA
- MC
- MD
- MG
- MV
- MX
- MH
- MK
- ML
- MT
- MM
- ME
- MN
- MP
- MZ
- MR
- MS
- MQ
- MU
- MW
- MY
- YT
- NA
- NC
- NE
- NF
- NG
- NI
- NU
- NL
- 'NO'
- NP
- NR
- NZ
- OM
- PK
- PA
- PN
- PE
- PH
- PW
- PG
- PL
- PR
- KP
- PT
- PY
- PS
- PF
- QA
- RE
- RO
- RU
- RW
- SA
- SD
- SN
- SG
- GS
- SH
- SJ
- SB
- SL
- SV
- SM
- SO
- PM
- RS
- SS
- ST
- SR
- SK
- SI
- SE
- SZ
- SX
- SC
- SY
- TC
- TD
- TG
- TH
- TJ
- TK
- TM
- TL
- TO
- TT
- TN
- TR
- TV
- TW
- TZ
- UG
- UA
- UM
- UY
- US
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- ZA
- ZM
- ZW
description: >
2-letter country code in ISO
3166-1 alpha format,
e.g. FR for France and GB for the United
Kingdom.
OrderFeesAPISchema:
title: OrderFeesAPISchema
type: object
required:
- amount
properties:
amount:
minimum: 0
type: integer
format: int64
description: >-
The fee amount charged to the customer, in minor units. e.g. for
$7, use `700`.
type:
type: string
description: The type of fee.
minLength: 1
maxLength: 255
description:
type: string
description: A description of the fee, e.g. "Currency Conversion Fee".
minLength: 1
maxLength: 255
OrderShippingAPISchema:
title: OrderShippingAPISchema
type: object
properties:
amount:
minimum: 0
type: integer
format: int64
description: >-
The shipping amount charged to the customer, in minor units. e.g.
for $7, use `700`.
methodId:
type: string
description: >-
Your unique identifier of the shipping method selected by the
customer.
methodName:
type: string
description: >-
The display label for the selected shipping method (e.g. "Standard
Shipping").
methodDescription:
type: string
description: >-
The descriptive text that is displayed alongside the shipping method
name.
OptionalAddressAPISchema:
title: OptionalAddressAPISchema
type: object
properties:
firstName:
title: First Name
type: string
minLength: 1
maxLength: 512
lastName:
title: Last Name
type: string
minLength: 1
maxLength: 512
addressLine1:
title: Address Line 1
type: string
description: Street name, Company name or PO Box
minLength: 1
maxLength: 255
addressLine2:
title: Address Line 2
type: string
description: Apartment, Unit or Building number
maxLength: 255
city:
title: City
type: string
description: Name of the city, district, town or village
minLength: 1
maxLength: 255
state:
title: State
type: string
description: State, County or Province
minLength: 1
maxLength: 255
countryCode:
$ref: '#/components/schemas/CountryCodeEnum'
title: Country Code
description: Two letter ISO country code
postalCode:
title: Postal Code
type: string
description: Postal or ZIP code
minLength: 1
maxLength: 255
RecurringPaymentTypeSchema:
title: Recurring Payment Type
type: string
enum:
- FIRST_PAYMENT
- ECOMMERCE
- SUBSCRIPTION
- UNSCHEDULED
description: >
Payment types, primarily to be used for recurring payments.
See the table below for all possible values.
Note: if no field is set, we will return a blank value and make a best
effort
to calculate the downstream fields required for processing the payment.
| paymentType | Use case |
| --- | --- |
| `FIRST_PAYMENT` | a customer-initiated payment which is the first in a
series of recurring payments or subscription, or a card on file
scenario. |
| `ECOMMERCE` | a customer-initiated payment using stored payment
details where the cardholder is present. |
| `SUBSCRIPTION` | a merchant-initiated payment as part of a series of
payments on a fixed schedule and a set amount. |
| `UNSCHEDULED` | a merchant-initiated payment using stored payment
details with no fixed schedule or amount. |
PaymentMethodTypeEnum:
title: PaymentMethodTypeEnum
enum:
- PAYMENT_CARD
- GOOGLE_PAY
- APPLE_PAY
- PAYPAL
- BANK_ACCOUNT
- KLARNA
- APAYA
- OPENNODE
- HOOLAH
- ATOME
- COINBASE
- NETS
- TWOC2P
- CLEARPAY
- SHOPEEPAY
- TRIPLE_A
- AFTERPAY
- NOL_PAY
- PAY_NL_IDEAL
- PAY_NL_BANCONTACT
- PAY_NL_DIRECT_DEBIT
- PAY_NL_SOFORT_BANKING
- PAY_NL_PAYPAL
- PAY_NL_PAYCONIQ
- PAY_NL_GIROPAY
- PAY_NL_P24
- PAY_NL_EPS
- PAY_NL_KAARTDIRECT
- ADYEN_SOFORT
- ADYEN_TWINT
- ADYEN_GIROPAY
- ADYEN_TRUSTLY
- ADYEN_ALIPAY
- ADYEN_MOBILEPAY
- ADYEN_MULTIBANCO
- ADYEN_VIPPS
- ADYEN_DOTPAY
- ADYEN_IDEAL
- ADYEN_BLIK
- ADYEN_PAYTRAIL
- ADYEN_INTERAC
- ADYEN_PAYSHOP
- ADYEN_MBWAY
- ADYEN_AFFIRM
- ADYEN_KLARNA
- ADYEN_BANCONTACT_PAYCONIQ
- ADYEN_EPS
- ADYEN_BANCONTACT_CARD
- ADYEN_SWISH
- MOLLIE_IDEAL
- MOLLIE_BANCONTACT
- MOLLIE_P24
- MOLLIE_GIROPAY
- MOLLIE_EPS
- MOLLIE_GIFTCARD
- MOLLIE_SOFORT
- NETAXEPT_PAYTRAIL
- BUCKAROO_IDEAL
- BUCKAROO_BANCONTACT
- BUCKAROO_SOFORT
- BUCKAROO_GIROPAY
- BUCKAROO_EPS
- RAPYD_GCASH
- RAPYD_PROMPTPAY
- RAPYD_GRABPAY
- RAPYD_POLI
- RAPYD_FAST
- XFERS_PAYNOW
- STRIPE_GIROPAY
- STRIPE_IDEAL
- ALIPAY_CN
- CHAI_KAKAOPAY
- CHAI_NAVER
- CHAI_TOSS
- XENDIT_DANA
- XENDIT_OVO
- XENDIT_SHOPEEPAY
- XENDIT_RETAIL_OUTLETS
- OMISE_PROMPTPAY
- OMISE_TRUEMONEY
- EBANX_PAGOFACIL
- PACYPAY_WECHAT
- PACYPAY_ALIPAY
- PACYPAY_ALIPAY_PLUS
- WORLDPAY_IDEAL
- IPAY88_CARD
- INGENICO_PAYPAL
- VOLT_PIX
- VOLT_BANK_TRANSFER
- BRAINTREE_VENMO
- THUNES_SPIRIT_OF_CADEAU
- THUNES_ILLICADO
- THUNES_CARTE_CADEAU_CONFORAMA
- THUNES_CHEQUE_FIDELITE_CONFORAMA
- SIPS_CPAY
- SIPS_CPAYCONFORAMA
- MONEXT_CETELEM
- MONEXT_CPAY
type: string
description: >-
Payment method type, where `OFF_SESSION_PAYMENT` is used for APM
(Alternative Payment Method) payments and `PAYMENT_CARD` for traditional
debit or credit cards. Please note that this list is different from one
indicated on [available payment
methods](/docs/connections/payment-methods/available-payment-methods)
page and values of this field will be changed in the future versions of
the API.
PaymentCardTokenAPISchema:
title: PaymentCardTokenAPISchema
required:
- last4Digits
- expirationMonth
- expirationYear
type: object
properties:
first6Digits:
title: Payment card's first six digits
maxLength: 6
minLength: 6
type: string
last4Digits:
title: Payment card's last four digits
maxLength: 4
minLength: 4
type: string
expirationMonth:
title: Expiration month
maxLength: 2
minLength: 2
type: string
expirationYear:
title: Expiration year
maxLength: 4
minLength: 4
type: string
cardholderName:
title: Cardholder's name
type: string
network:
title: Card network
type: string
isNetworkTokenized:
title: Is represented by a digital PAN
type: boolean
default: false
binData:
$ref: '#/components/schemas/BinDataAPISchema'
PayPalOrderTokenAPISchema:
title: PayPalOrderTokenAPISchema
required:
- paypalOrderId
type: object
properties:
paypalOrderId:
title: PayPal order identifier
type: string
externalPayerInfo:
$ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
title: Payer Info
description: Information about the PayPal customer
paypalStatus:
title: PayPal order status
type: string
PayPalBillingAgreementAPISchema:
title: PayPalBillingAgreementAPISchema
required:
- paypalBillingAgreementId
type: object
properties:
paypalBillingAgreementId:
title: Paypalbillingagreementid
type: string
externalPayerInfo:
$ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
title: Payer Info
description: Information about the PayPal customer
shippingAddress:
$ref: '#/components/schemas/AddressAPISchema'
title: Shipping address
description: The PayPal customer's shipping address
paypalStatus:
title: PayPal order status
type: string
GoCardlessMandateAPISchema:
title: GoCardlessMandateAPISchema
required:
- gocardlessMandateId
type: object
properties:
gocardlessMandateId:
title: Mandate agreement ID
type: string
description: Unique identifier of a GoCardless mandate agreement
KlarnaPaymentSessionAPISchema:
title: KlarnaPaymentSessionAPISchema
required:
- klarnaAuthorizationToken
- sessionData
type: object
properties:
klarnaAuthorizationToken:
title: Klarnaauthorizationtoken
type: string
sessionData:
$ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
KlarnaCustomerTokenAPISchema:
title: KlarnaCustomerTokenAPISchema
required:
- klarnaCustomerToken
- sessionData
type: object
properties:
klarnaCustomerToken:
title: Klarnacustomertoken
type: string
sessionData:
$ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
IdealPayNLTokenAPISchema:
title: IdealPayNLTokenAPISchema
required:
- paymentMethodConfigId
type: object
properties:
paymentMethodConfigId:
title: Paymentmethodconfigid
type: string
format: uuid
ApayaCustomerTokenAPISchema:
title: ApayaCustomerTokenAPISchema
required:
- mx
type: object
properties:
mx:
title: Mx
type: string
mnc:
title: Mnc
type: integer
format: int64
mcc:
title: Mcc
type: integer
format: int64
ThreeDSecureAuthenticationAPISchema:
title: ThreeDSecureAuthenticationAPISchema
required:
- responseCode
type: object
properties:
responseCode:
$ref: '#/components/schemas/ThreeDSecureAuthResponseCodeEnum'
reasonCode:
title: Reasoncode
anyOf:
- $ref: '#/components/schemas/ThreeDSecureSkippedReasonCodeEnum'
- $ref: '#/components/schemas/ThreeDSecureFailedReasonCodeEnum'
reasonText:
title: Reasontext
type: string
protocolVersion:
title: Protocolversion
type: string
challengeIssued:
title: Challengeissued
type: boolean
AuthorizationTypeEnum:
title: AuthorizationTypeEnum
enum:
- ESTIMATED
- FINAL
type: string
description: Type of authorization for the payment.
BlockingPaymentActionTypeEnum:
title: BlockingPaymentActionTypeEnum
enum:
- 3DS_AUTHENTICATION
- USE_PRIMER_SDK
- PAYMENT_METHOD_VOUCHER
- PROCESSOR_3DS
type: string
description: An enumeration.
PaymentStatusTypeEnum:
title: PaymentStatusTypeEnum
enum:
- APPLICATION_ERROR
- GATEWAY_REJECTED
- GATEWAY_TIMEOUT
- ISSUER_DECLINED
type: string
description: >
The status reason type for the payment, providing more information on
the error.
`APPLICATION_ERROR` indicates something went wrong internally within
primer's system.
`GATEWAY_REJECTED` indicates that request was rejected on the
third-party.
`GATEWAY_TIMEOUT` indicates the timeout limit on the third party request
was exceeded.
`ISSUER_DECLINED` indicates a legitimate decline that is not due to a
timeout.
DeclineTypeEnum:
title: DeclineTypeEnum
enum:
- SOFT_DECLINE
- HARD_DECLINE
type: string
description: An enumeration.
TransactionDeclineReasonV2Enum:
title: TransactionDeclineReasonV2Enum
enum:
- ERROR
- INVALID_CARD_NUMBER
- EXPIRED_CARD
- LOST_OR_STOLEN_CARD
- SUSPECTED_FRAUD
- UNKNOWN
- DECLINED
- REFER_TO_CARD_ISSUER
- DO_NOT_HONOR
- INSUFFICIENT_FUNDS
- WITHDRAWAL_LIMIT_EXCEEDED
- ISSUER_TEMPORARILY_UNAVAILABLE
- AUTHENTICATION_REQUIRED
type: string
description: An enumeration.
AdvisedActionEnum:
title: AdvisedActionEnum
enum:
- RETRY_LATER
- UPDATE_DATA
- DO_NOT_RETRY
- STOP_ALL_PAYMENTS
type: string
description: >
The Primer-recommended action to take based on the underlying decline
reason and advice code. This advised action is unified across all
supported processors and payment methods.
- `RETRY_LATER`: The payment was likely declined due to a temporary
issue (e.g. Insufficient funds). The payment can be retried immediately
or at a later date.
- `UPDATE_DATA`: The payment was likely declined because critical data
was missing or out-of-date. Please ensure you use the most up-to-date
payment information and customer details before retrying the payment.
- `DO_NOT_RETRY`: The payment was declined and should not be retried.
You can still charge this payment method for future orders or
installments.
- `STOP_ALL_PAYMENTS`: The processor or payment method explicitly
informs you to stop making any payment requests with this payment
method. Please use another payment method to charge this customer.
- `null`: Primer is unable to determine a recommended action.
TransactionTypeEnum:
title: TransactionTypeEnum
enum:
- SALE
- REFUND
type: string
description: An enumeration.
TransactionEventApiResponse:
type: object
required:
- id
- date
- type
properties:
id:
type: string
description: The id of the event.
format: uuid
example: 46d25279-9d36-4237-8f45-2dc4e4e262d6
processorEventId:
type: string
description: The ID of the event from the payment processor (e.g. PayPal).
example: 30B258847H402782C
date:
type: string
format: date-time
description: Timestamp of when the event occurred.
example: '2025-01-22T13:39:18.992928'
type:
type: string
description: The type of the event.
enum:
- AUTHORIZATION_SUCCEEDED
- AUTHORIZATION_ADJUSTMENT_SUCCEEDED
- CAPTURE_SUCCEEDED
- CANCELLATION_SUCCEEDED
- AUTHORIZATION_FAILED
- AUTHORIZATION_DECLINED
- AUTHORIZATION_ADJUSTMENT_FAILED
- AUTHORIZATION_ADJUSTMENT_DECLINED
- CAPTURE_FAILED
- CAPTURE_DECLINED
- CANCELLATION_FAILED
- CANCELLATION_DECLINED
example: CAPTURE_SUCCEEDED
amount:
type: integer
format: int64
description: The amount associated with the event in minor units.
example: 1234
final:
type: boolean
description: >-
Indicates whether the event is final.
For example, in the case of a capture event this would indicate
whether it was a final capture or not, but in the case of a
cancellation request this field will not be present.
example: false
processorStatusReason:
description: >-
The reason for the failure or decline. Present only on failed or
declined events, null for success events. The
`processorStatusReason` at the transaction level always reflects the
value of the most recent failed or declined event.
allOf:
- $ref: '#/components/schemas/StatusReasonAPISchema'
FraudCheckAPISchema:
title: FraudCheckAPISchema
description: |
Results of the pre-authorization and post-authorization fraud checks.
type: object
properties:
source:
type: string
example: FRAUD_PROVIDER
preAuthorizationResult:
$ref: '#/components/schemas/PreAuthFraudDecisionTypeEnum'
example: THREE_DS
preAuthorizationRecommendation:
$ref: '#/components/schemas/PreAuthorizationRecommendationEnum'
example: TRANSACTION_RISK_ANALYSIS
postAuthorizationResult:
$ref: '#/components/schemas/PostAuthFraudDecisionTypeEnum'
example: ACCEPT
CVVCheckAPISchema:
title: CVVCheckAPISchema
description: |
Results of any external CVV check performed on this payment.
required:
- source
- result
type: object
properties:
source:
type: string
example: PROCESSOR
result:
$ref: '#/components/schemas/RiskAssessmentStatusEnum'
example: MATCHED
AVSCheckAPISchema:
title: AVSCheckAPISchema
description: |
Results of any external AVS check performed on this payment.
required:
- source
- result
type: object
properties:
source:
type: string
example: PROCESSOR
result:
$ref: '#/components/schemas/AVSRiskAssessmentValues'
ProductTypeEnum:
title: ProductTypeEnum
enum:
- PHYSICAL
- DIGITAL
type: string
description: An enumeration
OrderLineItemsProductDataAPISchema:
title: OrderLineItemsProductDataAPISchema
description: Details related to the product
type: object
properties:
sku:
title: SKU
type: string
description: The product SKU
minLength: 1
maxLength: 255
brand:
title: Brand
type: string
description: The product brand
minLength: 1
maxLength: 255
color:
title: Color
type: string
description: The product color
minLength: 1
maxLength: 255
globalTradeItemNumber:
title: Global Trade Item Number
type: string
description: The product Global Trade Item Number (e.g. ISBN)
minLength: 1
maxLength: 255
manufacturerPartNumber:
title: Manufacturer Part Number
type: string
description: The product Manufacturer Part Number
minLength: 1
maxLength: 255
weight:
title: Weight
type: number
description: The product weight
minimum: 0
weightUnit:
title: Weight Unit
type: string
description: The product weight unit (e.g. kg, g)
minLength: 1
maxLength: 255
pageUrl:
title: Page URL
type: string
description: The product page URL
minLength: 1
maxLength: 1024
BinDataAPISchema:
title: BinDataAPISchema
required:
- network
- regionalRestriction
- accountNumberType
- accountFundingType
- prepaidReloadableIndicator
- productUsageType
- productCode
- productName
type: object
properties:
network:
$ref: '#/components/schemas/CardNetworkEnum'
issuerCountryCode:
$ref: '#/components/schemas/CountryCodeEnum'
issuerName:
title: Issuername
type: string
issuerCurrencyCode:
$ref: '#/components/schemas/Currency'
regionalRestriction:
$ref: '#/components/schemas/CardRegionRestrictionEnum'
accountNumberType:
$ref: '#/components/schemas/CardAccountNumberTypeEnum'
accountFundingType:
$ref: '#/components/schemas/AccountFundingTypeEnum'
prepaidReloadableIndicator:
$ref: '#/components/schemas/PrepaidReloadableEnum'
productUsageType:
$ref: '#/components/schemas/CardProductTypeEnum'
productCode:
title: Productcode
type: string
productName:
title: Productname
type: string
PayPalExternalPayerInfoAPISchema:
title: PayPalExternalPayerInfoAPISchema
type: object
properties:
externalPayerId:
title: Externalpayerid
type: string
email:
title: Email
type: string
firstName:
title: Firstname
type: string
lastName:
title: Lastname
type: string
AddressAPISchema:
title: AddressAPISchema
required:
- addressLine1
- city
- countryCode
type: object
properties:
firstName:
title: First Name
type: string
lastName:
title: Last Name
type: string
addressLine1:
title: Address Line 1
type: string
description: Street name, Company name or PO Box
addressLine2:
title: Address Line 2
type: string
description: Apartment, Unit or Building number
city:
title: City
type: string
description: Name of the city, district, town or village
state:
title: State
type: string
description: State, County or Province
countryCode:
$ref: '#/components/schemas/CountryCodeEnum'
title: Country Code
description: Two letter ISO country code
postalCode:
title: Postal Code
type: string
description: Postal or ZIP code
KlarnaSessionDetailsAPISchema:
title: KlarnaSessionDetailsAPISchema
required:
- billingAddress
- purchaseCountry
- purchaseCurrency
- locale
- orderLines
type: object
properties:
recurringDescription:
title: Recurringdescription
type: string
billingAddress:
$ref: '#/components/schemas/KlarnaAddressAPISchema'
shippingAddress:
$ref: '#/components/schemas/KlarnaAddressAPISchema'
purchaseCountry:
title: Purchasecountry
type: string
purchaseCurrency:
title: Purchasecurrency
type: string
locale:
title: Locale
type: string
orderLines:
title: Orderlines
type: array
items: {}
tokenDetails:
$ref: '#/components/schemas/KlarnaTokenDetails'
ThreeDSecureAuthResponseCodeEnum:
title: ThreeDSecureAuthResponseCodeEnum
enum:
- NOT_PERFORMED
- SKIPPED
- AUTH_SUCCESS
- AUTH_FAILED
- CHALLENGE
- METHOD
type: string
description: An enumeration.
ThreeDSecureSkippedReasonCodeEnum:
title: ThreeDSecureSkippedReasonCodeEnum
enum:
- GATEWAY_UNAVAILABLE
- DISABLED_BY_MERCHANT
- NOT_SUPPORTED_BY_ISSUER
- FAILED_TO_NEGOTIATE
- UNKNOWN_ACS_RESPONSE
- 3DS_SERVER_ERROR
- ACQUIRER_NOT_CONFIGURED
- ACQUIRER_NOT_PARTICIPATING
- EXEMPTION_ACCEPTED
type: string
description: An enumeration.
ThreeDSecureFailedReasonCodeEnum:
title: ThreeDSecureFailedReasonCodeEnum
enum:
- UNKNOWN
- REJECTED_BY_ISSUER
- CARD_AUTHENTICATION_FAILED
- UNKNOWN_DEVICE
- UNSUPPORTED_DEVICE
- EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT
- EXPIRED_CARD
- INVALID_CARD_NUMBER
- INVALID_TRANSACTION
- NO_CARD_RECORD
- SECURITY_FAILURE
- STOLEN_CARD
- SUSPECTED_FRAUD
- TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER
- CARDHOLDER_NOT_ENROLLED_IN_SERVICE
- TRANSACTION_TIMED_OUT_AT_THE_ACS
- LOW_CONFIDENCE
- MEDIUM_CONFIDENCE
- HIGH_CONFIDENCE
- VERY_HIGH_CONFIDENCE
- EXCEEDS_ACS_MAXIMUM_CHALLENGES
- NON_PAYMENT_NOT_SUPPORTED
- THREE_RI_NOT_SUPPORTED
- ACS_TECHNICAL_ISSUE
- DECOUPLED_REQUIRED_BY_ACS
- DECOUPLED_MAX_EXPIRY_EXCEEDED
- DECOUPLED_AUTHENTICATION_INSUFFICIENT_TIME
- AUTHENTICATION_ATTEMPTED_BUT_NOT_PERFORMED_BY_CARDHOLDER
- ACS_TIMED_OUT
- INVALID_ACS_RESPONSE
- ACS_SYSTEM_ERROR_RESPONSE
- ERROR_GENERATING_CAVV
- PROTOCOL_VERSION_NOT_SUPPORTED
- TRANSACTION_EXCLUDED_FROM_ATTEMPTS_PROCESSING
- REQUESTED_PROGRAM_NOT_SUPPORTED
type: string
description: >-
This enum is derived from the `transStatusReason` on page 218 of the
[EMV Co 3DS protocol
specification](https://www.emvco.com/terms-of-use/?u=/wp-content/uploads/documents/EMVCo_3DS_Spec_v220_122018.pdf)
| Code | Description |
|------|-----------------------------------------|
| 01 | Card authentication failed |
| 02 | Unknown Device |
| 03 | Unsupported Device |
| 04 | Exceeds authentication frequency limit |
| 05 | Expired card |
| 06 | Invalid card number |
| 07 | Invalid transaction |
| 08 | No Card record |
| 09 | Security failure |
| 10 | Stolen card |
| 11 | Suspected fraud |
| 12 | Transaction not permitted to cardholder |
| 13 | Cardholder not enrolled in service |
| 14 | Transaction timed out at the ACS |
| 15 | Low confidence |
| 16 | Medium confidence |
PreAuthFraudDecisionTypeEnum:
title: PreAuthFraudDecisionTypeEnum
enum:
- ACCEPT
- REFUSE
- FAILED
- THREE_DS
- THREE_DS_EXEMPTION
type: string
description: Possible pre-authorization fraud check outcomes.
PreAuthorizationRecommendationEnum:
title: PreAuthorizationRecommendationEnum
enum:
- TRANSACTION_RISK_ANALYSIS
type: string
description: >
Pre-authorization recommendation indicating the SCA exemption or risk
assessment path taken. Only present when `preAuthorizationResult` is
`THREE_DS_EXEMPTION`.
Values:
- `TRANSACTION_RISK_ANALYSIS`: Indicates that the fraud check deemed the
transaction low risk and recommends applying a Transaction Risk Analysis
(TRA) exemption to bypass Strong Customer Authentication (SCA) under
PSD2, reducing friction for users.
PostAuthFraudDecisionTypeEnum:
title: PostAuthFraudDecisionTypeEnum
enum:
- ACCEPT
- REFUSE
- FAILED
- THREE_DS
type: string
description: Possible post-authorization fraud check outcomes.
RiskAssessmentStatusEnum:
title: RiskAssessmentStatusEnum
enum:
- MATCHED
- NOT_MATCHED
- NOT_VERIFIED
- NOT_PROVIDED
- NOT_APPLICABLE
- SKIPPED
type: string
description: Possible risk assessment values for CVV and AVS checks.
AVSRiskAssessmentValues:
title: AVSRiskAssessmentValues
type: object
required:
- streetAddress
- postalCode
properties:
streetAddress:
$ref: '#/components/schemas/RiskAssessmentStatusEnum'
example: NOT_MATCHED
postalCode:
$ref: '#/components/schemas/RiskAssessmentStatusEnum'
example: NOT_VERIFIED
CardNetworkEnum:
title: CardNetworkEnum
enum:
- AMEX
- DANKORT
- DINERS_CLUB
- DISCOVER
- ENROUTE
- ELO
- HIPER
- INTERAC
- JCB
- MAESTRO
- MASTERCARD
- MIR
- PRIVATE_LABEL
- UNIONPAY
- VISA
- CARTES_BANCAIRES
- OTHER
type: string
description: |
The list of available card networks.
CardRegionRestrictionEnum:
title: CardRegionRestrictionEnum
enum:
- DOMESTIC_USE_ONLY
- NONE
- UNKNOWN
type: string
description: An enumeration.
CardAccountNumberTypeEnum:
title: CardAccountNumberTypeEnum
enum:
- PRIMARY_ACCOUNT_NUMBER
- NETWORK_TOKEN
- DIGITAL_PAN
- UNKNOWN
type: string
description: An enumeration.
AccountFundingTypeEnum:
title: AccountFundingTypeEnum
enum:
- CREDIT
- DEBIT
- PREPAID
- CHARGE
- DEFERRED_DEBIT
- UNKNOWN
type: string
description: An enumeration.
PrepaidReloadableEnum:
title: PrepaidReloadableEnum
enum:
- RELOADABLE
- NON_RELOADABLE
- NOT_APPLICABLE
- UNKNOWN
type: string
description: An enumeration.
CardProductTypeEnum:
title: CardProductTypeEnum
enum:
- CONSUMER
- BUSINESS
- GOVERNMENT
- UNKNOWN
type: string
description: An enumeration.
KlarnaAddressAPISchema:
title: KlarnaAddressAPISchema
type: object
properties:
title:
title: Title
type: string
firstName:
title: Firstname
type: string
lastName:
title: Lastname
type: string
email:
title: Email
type: string
phoneNumber:
title: Phonenumber
type: string
addressLine1:
title: Addressline1
type: string
addressLine2:
title: Addressline2
type: string
addressLine3:
title: Addressline3
type: string
city:
title: City
type: string
state:
title: State
type: string
countryCode:
$ref: '#/components/schemas/CountryCodeEnum'
postalCode:
title: Postalcode
type: string
KlarnaTokenDetails:
title: KlarnaTokenDetails
required:
- type
type: object
properties:
type:
title: Type
type: string
brand:
title: Brand
type: string
masked_number:
title: Masked Number
type: string
expiry_date:
title: Expiry Date
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````