> ## 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.
# Payment Status Update
> Primer notifies you with a `PAYMENT.STATUS` webhook when a payment's status
has been updated. This is especially useful for asyncronous processor Connections,
which do not respond with an upfront authorization.
The webhook events will arrive in the order that the payment status changes,
for example you should expect a status of `PENDING`, then `AUTHORIZED`, then
`SETTLED` (depending on how your workflow is set up).
The webhook body contains the full payment object.
```json Webhook theme={"dark"}
Version - 2.4
```
```json Example payment status notification theme={"dark"}
{
"eventType":"PAYMENT.STATUS",
"date":"2021-02-21T15:36:16.367687",
"notificationConfig":{
"id":"cc51f9f0-7e1c-492b-9d37-f83a818f6070",
"description":"Payment webhook"
},
"version":"2.4",
"signedAt": "1689221338",
"payment":{
"id":"DdRZ6YY0",
"date":"2021-02-21T15:34:16.367687",
"dateUpdated":"2021-02-21T15:35:16.133701",
"amount":3000,
"currencyCode":"GBP",
"customerId":"cust-123",
"orderId":"order-123",
"status":"SETTLED",
"cardTokenType":"CARD_PAN",
"customer": {
"emailAddress": "test@primer.io",
"mobileNumber": "0123456789",
"billingAddress": {
"firstName": "John",
"postalCode": "CB94BQ",
"addressLine1": "10001 Alpha St",
"countryCode": "GB",
"city": "Cambridge",
"state": "Cambridgeshire"
}
},
"paymentMethod":{
"paymentType":"FIRST_PAYMENT",
"paymentMethodToken":"-lcWjvBAAs2DnIRXwxNjUzNTYzNjIy",
"isVaulted": "false",
"analyticsId":"LUi5pETUaVsdSEamK25L",
"paymentMethodType":"PAYMENT_CARD",
"paymentMethodData":{
"last4Digits":"1111",
"first6Digits": "411111",
"expirationMonth":"03",
"expirationYear":"2030",
"cardholderName":"ADYEN",
"network":"Visa",
"isNetworkTokenized":false,
"binData":{
"network":"VISA",
"issuerCountryCode":"US",
"issuerName":"JPMORGAN CHASE BANK, N.A.",
"regionalRestriction":"UNKNOWN",
"accountNumberType":"UNKNOWN",
"accountFundingType":"UNKNOWN",
"prepaidReloadableIndicator":"NOT_APPLICABLE",
"productUsageType":"UNKNOWN",
"productCode":"UNKNOWN",
"productName":"UNKNOWN"
}
},
"authorizationType": "FINAL",
"threeDSecureAuthentication":{
"responseCode":"NOT_PERFORMED"
}
},
"processor":{
"name":"STRIPE",
"processorMerchantId":"acct_1GORasdasqNWFwi8c",
"amountCaptured":3000,
"amountRefunded":0
},
"transactions":[
{
"date":"2021-02-21T15:34:16.367687",
"amount":3000,
"currencyCode":"GBP",
"transactionType":"SALE",
"orderId":"order-123",
"processorTransactionId":"pi_3L3edsGZasdasdc1iget38p",
"processorName":"STRIPE",
"processorMerchantId":"acct_1GORasvasdNWFwi8c",
"processorStatus":"SETTLED",
"cardTokenType":"CARD_PAN"
}
],
"riskData":{
"fraudChecks":{
"source":"riskified",
"preAuthorizationResult":"THREE_DS_EXEMPTION",
"preAuthorizationRecommendation":"TRANSACTION_RISK_ANALYSIS",
"postAuthorizationResult":"ACCEPT"
},
"cvvCheck": {
"source": "processor",
"result": "MATCHED"
},
"avsCheck": {
"source": "processor",
"result": {
"streetAddress": "NOT_MATCHED",
"postalCode": "NOT_VERIFIED"
}
}
}
}
}
```
Learn more about [how Primer handles webhooks](/api-reference/get-started/configure-webhooks).
## OpenAPI
````yaml https://api.schemas.primer.io/api-reference/v2.4/webhooks.yaml post /payment-status
openapi: 3.0.2
info:
x-logo:
url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
title: Primer Webhooks
version: '2.4'
description: Webhooks specifications for Primer API v2.4
servers:
- url: https://api.sandbox.primer.io
- url: https://api.primer.io
security: []
paths:
/payment-status:
post:
tags:
- Payment Webhooks
summary: Payment Status Update
description: >
Primer notifies you with a `PAYMENT.STATUS` webhook when a payment's
status
has been updated. This is especially useful for asyncronous processor
Connections,
which do not respond with an upfront authorization.
The webhook events will arrive in the order that the payment status
changes,
for example you should expect a status of `PENDING`, then `AUTHORIZED`,
then
`SETTLED` (depending on how your workflow is set up).
The webhook body contains the full payment object.
operationId: payment_status_webhook_event
parameters:
- in: header
name: X-Signature-Primary
schema:
type: string
required: true
description: >-
An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated
using the webhook payload and a shared signing secret. This is then
converted to a base64 encoded string.
- in: header
name: X-Signature-Secondary
schema:
type: string
required: true
description: >-
A secondary signature that is added when you have rotated your
secret within the past 24 hours.
requestBody:
content:
application/json:
schema:
title: Request
allOf:
- $ref: '#/components/schemas/PaymentStatusWebhookPayload'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
components:
schemas:
PaymentStatusWebhookPayload:
title: PaymentStatusWebhookPayload
type: object
required:
- eventType
- date
- signedAt
- notificationConfig
- payment
properties:
eventType:
title: Event Type
type: string
description: The type of the webhook raised. `PAYMENT.STATUS` in this case.
date:
title: Date
type: string
description: The date-time that the webhook was sent.
format: date-time
signedAt:
title: Signed At
type: string
description: The Unix timestamp at which the webhook payload was signed.
example: '1689221338'
notificationConfig:
title: Notification Config
type: object
required:
- id
- description
description: The notification configuration details.
properties:
id:
title: ID
type: string
description: The notification configuration ID.
format: uuid
description:
title: Description
type: string
description: The notification configuration description.
version:
title: Version
type: string
description: The payload version
example: '2.4'
payment:
title: Payment Details
type: object
required:
- id
- date
- dateUpdated
- amount
- currencyCode
- orderId
- status
- paymentMethod
- transactions
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: Date Updated
type: string
description: >-
The date-time that the update related to the webhook has
happened.
format: date-time
status:
title: Current status
allOf:
- $ref: '#/components/schemas/PaymentStatus'
description: >-
See the payment [status table](../docs#payment-status) for more
information.
orderId:
title: Order ID
type: string
description: Your reference for the payment.
currencyCode:
title: Currency
type: string
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.
customerId:
title: The ID of the customer using the checkout
type: string
description: The unique identifier for your customer.
metadata:
title: Payment Metadata
type: object
description: |
Additional data to be used throughout the payment lifecycle.
customer:
title: customer
type: object
properties:
emailAddress:
title: Email Address
type: string
description: |
Customer email address.
format: email
mobileNumber:
title: Mobile Number
type: string
description: The customer's mobile number
minLength: 1
maxLength: 255
firstName:
title: First Name
type: string
description: The customer's first name
minLength: 1
maxLength: 255
lastName:
title: Last Name
type: string
description: The customer's last name
minLength: 1
maxLength: 255
billingAddress:
$ref: '#/components/schemas/OptionalAddressAPISchema'
title: Billing Address
description: |
Customer billing address.
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
paymentMethod:
title: Payment Method Options
allOf:
- $ref: >-
#/components/schemas/PaymentResponsePaymentMethodOptionsAPISchema
description: >-
The payment method options provided in the request, as well as
the token used to process the payment.
processor:
title: Processor Information
allOf:
- $ref: '#/components/schemas/PaymentResponseProcessorAPISchema'
description: >-
More information associated with the payment processor,
including the processor name.
statusReason:
title: Status Reason
allOf:
- $ref: '#/components/schemas/StatusReasonAPISchema'
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
PaymentStatus:
title: PaymentStatus
enum:
- PENDING
- FAILED
- AUTHORIZED
- SETTLING
- PARTIALLY_SETTLED
- SETTLED
- DECLINED
- CANCELLED
type: string
description: An enumeration.
OptionalAddressAPISchema:
title: OptionalAddressAPISchema
type: object
properties:
firstName:
title: First Name
type: string
minLength: 1
maxLength: 255
lastName:
title: Last Name
type: string
minLength: 1
maxLength: 255
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
PaymentResponsePaymentMethodOptionsAPISchema:
title: PaymentResponsePaymentMethodOptionsAPISchema
type: object
properties:
descriptor:
title: Payment descriptor
type: string
description: >-
The description of the payment, as it would typically appear on a
bank statement.
paymentType:
allOf:
- $ref: '#/components/schemas/RecurringPaymentTypeSchema'
paymentMethodToken:
title: Payment Method Token
type: string
description: The payment method token used to authorize the transaction.
isVaulted:
title: Boolean flag indicating if a payment method token was vaulted
type: boolean
description: >-
If the payment method token was vaulted, this is set to `true`. Use
this token for recurring payments.
analyticsId:
title: Unique analytics ID
type: string
description: Unique analytics identifier corresponding to a payment method
paymentMethodType:
title: Payment method type
allOf:
- $ref: '#/components/schemas/PaymentMethodTypeEnum'
description: Payment method type
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:
title: Threedsecureauthentication
allOf:
- $ref: '#/components/schemas/ThreeDSecureAuthenticationAPISchema'
default:
responseCode: NOT_PERFORMED
PaymentResponseProcessorAPISchema:
title: PaymentResponseProcessorAPISchema
type: object
properties:
name:
title: Processor Name
type: string
description: The payment processor used for this payment.
processorMerchantId:
title: Processor Merchant ID
type: string
description: >-
The merchant ID registered at the payment processor used for this
payment.
amountCaptured:
title: Amount captured
type: integer
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
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.
StatusReasonAPISchema:
title: StatusReasonAPISchema
required:
- type
type: object
properties:
type:
title: Payment status type
allOf:
- $ref: '#/components/schemas/PaymentStatusTypeEnum'
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.
declineType:
title: Decline Type
allOf:
- $ref: '#/components/schemas/DeclineTypeEnum'
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:
title: Payment status code
allOf:
- $ref: '#/components/schemas/TransactionDeclineReasonV2Enum'
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
- transactionType
- processorName
- processorMerchantId
- processorStatus
type: object
properties:
date:
title: Creation date
type: string
description: Date & time of the transaction (UTC)
format: date-time
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:
title: Processor Transaction status
allOf:
- $ref: '#/components/schemas/PaymentStatus'
description: >-
Transaction status, please refer to the [Transaction Status
Codes](#section/API-Usage-Guide/Payment-Status) table for more
information
processorStatusReason:
title: Payment error
allOf:
- $ref: '#/components/schemas/StatusReasonAPISchema'
description: |
If the transaction has a declined or failed status.
Only if the status is `DECLINED` or `FAILED`, otherwise `null`.
reason:
title: Reason
type: string
description: >
The reason for a cancel or refund request on this transaction, if
any.
example: Item returned.
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
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: An enumeration.
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
type: string
description: >
[The list of available payment methods and their `PAYMENT_METHOD_TYPE`
can be found
here.](https://primer.io/docs/connections/payment-methods/available-payment-methods)
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:
title: Payer Info
allOf:
- $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
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:
title: Payer Info
allOf:
- $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
description: Information about the PayPal customer
shippingAddress:
title: Shipping address
allOf:
- $ref: '#/components/schemas/AddressAPISchema'
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
mcc:
title: Mcc
type: integer
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
PaymentStatusTypeEnum:
title: PaymentStatusTypeEnum
enum:
- APPLICATION_ERROR
- GATEWAY_REJECTED
- ISSUER_DECLINED
- GATEWAY_TIMEOUT
type: string
description: An enumeration.
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.
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: Enumerates all supported currencies
TransactionTypeEnum:
title: TransactionTypeEnum
enum:
- SALE
- REFUND
type: string
description: An enumeration.
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.
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.
type: object
properties:
source:
type: string
example: PROCESSOR
result:
$ref: '#/components/schemas/AVSRiskAssessmentValues'
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:
title: Country Code
allOf:
- $ref: '#/components/schemas/CountryCodeEnum'
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
properties:
streetAddress:
$ref: '#/components/schemas/RiskAssessmentStatusEnum'
example: NOT_MATCHED
postalCode:
$ref: '#/components/schemas/RiskAssessmentStatusEnum'
example: NOT_VERIFIED
CardNetworkEnum:
title: CardNetworkEnum
type: string
enum:
- AMEX
- DANKORT
- DINERS_CLUB
- DISCOVER
- ENROUTE
- ELO
- HIPER
- INTERAC
- JCB
- MAESTRO
- MASTERCARD
- MIR
- PRIVATE_LABEL
- UNIONPAY
- VISA
- CARTES_BANCAIRES
- OTHER
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
- 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
````