{
"version": "2.3"
}
{}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
processorStatusisSETTLED, the refund was successful and the funds have been returned to the customer - if
processorStatusisFAILED, the refund was unsuccessful
Learn more about how Primer handles webhooks.
{
"version": "2.3"
}
{}{
"version": "2.3"
}
Headers
An HMAC signature generated using the webhook payload and a shared signing secret. This is then converted to a base64 encoded string.
A secondary signature that is added when you have rotated your secret within the past 24 hours.
Body
The type of the webhook raised. PAYMENT.REFUND in this case.
The date-time that the webhook was sent.
The payload version
"2.3"
Show child attributes
Show child attributes
The unique payment ID.
You can use this ID to retrieve the payment details, or perform downstream operations.
The date and time at which the payment was created in UTC format.
See the payment status table for more information.
PENDING, FAILED, AUTHORIZED, SETTLING, PARTIALLY_SETTLED, SETTLED, DECLINED, CANCELLED Your reference for the payment.
The 3-letter currency code in ISO 4217 format.
e.g. use USD for US dollars.
The amount you charged the customer, in minor units.
x >= 0The unique identifier for your customer.
Additional data to be used throughout the payment lifecycle.
Additional processor data to be used throughout the payment lifecycle.
Show child attributes
Show child attributes
Customer email address.
The customer's mobile number
1 - 256The customer's first name
1 - 256The customer's last name
1 - 256Customer billing address.
Show child attributes
Show child attributes
1 - 2561 - 256Street name, Company name or PO Box
1 - 256Apartment, Unit or Building number
256Name of the city, district, town or village
1 - 256State, County or Province
1 - 256Two letter ISO country code
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 Postal or ZIP code
1 - 256Customer shipping address
Show child attributes
Show child attributes
1 - 2561 - 256Street name, Company name or PO Box
1 - 256Apartment, Unit or Building number
256Name of the city, district, town or village
1 - 256State, County or Province
1 - 256Two letter ISO country code
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 Postal or ZIP code
1 - 256The customer's tax id number for tax exemptions
256The customer's national identification number
256The payment method options provided in the request, as well as the token used to process the payment.
Show child attributes
Show child attributes
The description of the payment, as it would typically appear on a bank statement.
Payment types, primarily to be used for recurring payments.
Note: If you successfully vault a SINGLE_USE token on payment creation, then there's no need to set a value for this field and it will be flagged as FIRST_PAYMENT. Otherwise, see the table below for all possible values.
| 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. |
FIRST_PAYMENT, ECOMMERCE, SUBSCRIPTION, UNSCHEDULED The payment method token used to authorize the transaction.
If the payment method token was vaulted, this is set to true. Use this token for recurring payments.
Unique analytics identifier corresponding to a payment method
Payment method type
Payment method data
- PaymentCardTokenAPISchema
- PayPalOrderTokenAPISchema
- PayPalBillingAgreementAPISchema
- GoCardlessMandateAPISchema
- KlarnaPaymentSessionAPISchema
- KlarnaCustomerTokenAPISchema
- IdealPayNLTokenAPISchema
- ApayaCustomerTokenAPISchema
Show child attributes
Show child attributes
4246Show child attributes
Show child attributes
The list of available card networks.
AMEX, DANKORT, DINERS_CLUB, DISCOVER, ENROUTE, ELO, HIPER, INTERAC, JCB, MAESTRO, MASTERCARD, MIR, PRIVATE_LABEL, UNIONPAY, VISA, CARTES_BANCAIRES, OTHER An enumeration.
DOMESTIC_USE_ONLY, NONE, UNKNOWN An enumeration.
PRIMARY_ACCOUNT_NUMBER, NETWORK_TOKEN, UNKNOWN An enumeration.
CREDIT, DEBIT, PREPAID, CHARGE, DEFERRED_DEBIT, UNKNOWN An enumeration.
RELOADABLE, NON_RELOADABLE, NOT_APPLICABLE, UNKNOWN An enumeration.
CONSUMER, BUSINESS, GOVERNMENT, UNKNOWN An enumeration.
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 Enumerates all supported currencies
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 Show child attributes
Show child attributes
An enumeration.
NOT_PERFORMED, SKIPPED, AUTH_SUCCESS, AUTH_FAILED, CHALLENGE, METHOD An enumeration.
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 More information associated with the payment processor, including the processor name.
Show child attributes
Show child attributes
The payment processor used for this payment.
The merchant ID registered at the payment processor used for this payment.
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.
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.
Check this field for more information regarding the payment's status. This is especially useful when the status is DECLINED or FAILED.
Show child attributes
Show child attributes
Type of the status.
APPLICATION_ERROR, GATEWAY_REJECTED, ISSUER_DECLINED 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.
SOFT_DECLINE, HARD_DECLINE If the error is of type ISSUER_DECLINED, this will be returned.
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 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.
A list summarizing the transactions that occurred while processing the payment.
Note: a refund is a separate transaction and so will appear in this transactions list if a refund was performed.
Show child attributes
Show child attributes
Processor's main account identifier.
- Adyen: Account code
- Braintree: Merchant ID
- Stripe: Account ID"
An enumeration.
SALE, REFUND Processor's unique identifier for the transaction
An identifier of a processor.
Transaction status, please refer to the Transaction Status Codes table for more information
PENDING, FAILED, AUTHORIZED, SETTLING, PARTIALLY_SETTLED, SETTLED, DECLINED, CANCELLED If the transaction has a declined or failed status.
Only if the status is DECLINED or FAILED, otherwise null.
Show child attributes
Show child attributes
Type of the status.
APPLICATION_ERROR, GATEWAY_REJECTED, ISSUER_DECLINED 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.
SOFT_DECLINE, HARD_DECLINE If the error is of type ISSUER_DECLINED, this will be returned.
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 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.
The reason for a cancel or refund request on this transaction, if any.
"Item returned."
Risk data associated with this payment.
Show child attributes
Show child attributes
Results of the pre-authorization and post-authorization fraud checks.
Show child attributes
Show child attributes
"FRAUD_PROVIDER"
Possible fraud check outcomes.
ACCEPT, REFUSE, FAILED, THREE_DS "THREE_DS"
Possible fraud check outcomes.
ACCEPT, REFUSE, FAILED, THREE_DS "ACCEPT"
Results of any external CVV check performed on this payment.
Results of any external AVS check performed on this payment.
Show child attributes
Show child attributes
"PROCESSOR"
Show child attributes
Show child attributes
Possible risk assessment values for CVV and AVS checks.
MATCHED, NOT_MATCHED, NOT_VERIFIED, NOT_PROVIDED, NOT_APPLICABLE, SKIPPED "NOT_MATCHED"
Possible risk assessment values for CVV and AVS checks.
MATCHED, NOT_MATCHED, NOT_VERIFIED, NOT_PROVIDED, NOT_APPLICABLE, SKIPPED "NOT_VERIFIED"
Response
Return a 200 status to indicate that the data was received successfully