> ## 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 Refund
> Primer notifies you with a `PAYMENT.REFUND` Webhook when a refund request has been fully processed by a payment processor and the refund has reached a final state.
Check the transaction with the most recent `transactionType: "REFUND"` in the `transactions` array:
- if `processorStatus` is `SETTLED`, the refund was successful and the funds have been returned to the customer
- if `processorStatus` is `FAILED`, the refund was unsuccessful
Learn more about [how Primer handles webhooks](/docs/api-reference/get-started/configure-webhooks).
```json Webhook theme={"dark"}
Version - 2.4
```
```json Example payment refund notification theme={"dark"}
{
"eventType":"PAYMENT.REFUND",
"date":"2021-02-21T15:37:16.367687",
"notificationConfig":{
"id":"cc51f9f0-7e1c-492b-9d37-f83a818f6070",
"description":"Refund webhook"
},
"version":"2.4",
"signedAt": "1689221398",
"payment":{
"id":"DdRZ6YY0",
"date":"2021-02-21T15:34:16.367687",
"dateUpdated":"2021-02-21T15:37:16.267687",
"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":3000
},
"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"
},
{
"date":"2021-02-21T15:37:16.267687",
"amount":3000,
"currencyCode":"GBP",
"transactionType":"REFUND",
"orderId":"order-123",
"processorTransactionId":"re_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-refund
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-refund:
post:
tags:
- Payment Webhooks
summary: Payment Refund
description: >
Primer notifies you with a `PAYMENT.REFUND` Webhook when a refund
request has been fully processed by a payment processor and the refund
has reached a final state.
Check the transaction with the most recent `transactionType: "REFUND"`
in the `transactions` array:
- if `processorStatus` is `SETTLED`, the refund was successful and the
funds have been returned to the customer
- if `processorStatus` is `FAILED`, the refund was unsuccessful
Learn more about [how Primer handles
webhooks](/docs/api-reference/get-started/configure-webhooks).
operationId: payment_refund_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/PaymentRefundWebhookPayload'
responses:
'200':
description: >-
Return a 200 status to indicate that the data was received
successfully
components:
schemas:
PaymentRefundWebhookPayload:
title: PaymentRefundWebhookPayload
type: object
required:
- eventType
- date
- signedAt
- notificationConfig
- payment
properties:
eventType:
title: Event Type
type: string
description: The type of the webhook raised. `PAYMENT.REFUND` 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
````