Payment Reversed Webhook
The PAYMENT_REVERSED webhook is sent when Rapyd reverses a payment. The status is set to REV.
The cancel_reason field specifies the reason for the reversal. For certain bank transfers, the failure_code and failure_message fields specify the reason for the reversal and the steps to correct it. See Bank Transfer Error Messages.
Note
The endpoint for webhooks is unique for each client. To set up a webhook endpoint, see Defining a Webhook Endpoint.
Content-Type
Indicates that the data appears in JSON format. Set to application/json.
salt
Random string.
signature
Signature calculated for each webhook individually.
timestamp
Timestamp for the webhook, in Unix time (seconds).
created_at
Time that the webhook was created, in Unix time.
Note
Inside the
dataobject, some webhooks have anothercreated_atfield that refers to a different event.
data
Contains the actual data of the webhook.
For details, see below.
extended_timestamp
Time in milliseconds that the webhook was created, in Unix time.
id
ID of the webhook. String starting with wh_.
status
Status of the webhook. One of the following:
NEW
CLO - Closed.
ERR - Error.
RET - Re-sent.
Note
Inside the
dataobject, some webhooks have anotherstatusfield that refers to a different event.
trigger_operation_id
ID of the operation that triggered the webhook. UUID.
type
Name of the webhook type.
Note
The name in the Client Portal is different.
address
Billing address associated with the payment. For details of fields in the 'address' object, see Create Address.
amount
The amount of the payment, in units of the currency defined in
currency.
auth_code
Indicates that the card payment was authorized by the card network.
cancel_reason
Reason for cancellation or reversal of a payment.
captured
Indicates whether the payment has been successfully captured.
complete_payment_url
URL where the customer is redirected when payment is successful, after returning from an external page such as a 3DS page. Does not support localhost URLs.
country_code
The country of the payment method.
created_at
Time of creation of the object, in Unix time.
currency_code
Transactions without FX - Indicates the currency of the amount received by the recipient.
FX transactions - Indicates the currency of the amount paid by the buyer.
customer_token
ID of the customer who is making the payment. String starting with cus_.
description
Description of the payment transaction.
destination_card
Filters the list for payments related to the specified destination card.
dispute
Details about the dispute, if the payment was disputed.
amount
Amount that Rapyd deducted from the merchant due to the dispute.
central_processing_date
The date the transaction was processed by the card network.
created_at
Time of creation of the dispute, in Unix time.
currency
Currency of the disputed transaction. Three-letter ISO 4217 code.
dispute_category
The category of dispute that was provided by the card network.
dispute_reason_description
A short description of the reason for the dispute.
due_date
The latest date for the dispute to be contested in Unix time.
evidence
Reserved.
evidence_reason_code
Reserved.
ewallet_id
ID of the wallet that the money is paid into. Relevant when the request includes a single wallet.
id
Reserved.
original_dispute_amount
Amount of the dispute, as reported to Rapyd.
original_dispute_currency
Currency of the disputed payment. Three-letter ISO 4217 code.
original_transaction_amount
Amount of the original payment.
original_transaction_currency
Currency of
original_transaction_amount. Three-letter ISO 4217 code.
original_transaction_id
ID of the payment that the dispute is charged against.
payment_method
ID of the payment method.
payment_method_data
Details of the payment method that was used for the payment.
pre_dispute
When true, indicates that the disputed payment was automatically refunded based on pre-determined criteria.
rate
FX rate. Relevant to FX payments.
status
Indicates the status of the dispute. One of the following values:
ACT (Active) - The dispute was initiated and is awaiting action by the merchant.
LOS (Lose) - The merchant lost the dispute. Funds were deducted from the merchant wallet. Final status.
RVW (Review) - Rapyd is reviewing the merchant's evidence contesting the dispute.
WIN (Win) - The merchant won the dispute. Funds were credited to the merchant wallet. Final status.
token
ID of the dispute.
updated_at
Time that the dispute was last updated, in Unix time.
error_code
Error code for the failure of the payment.
error_message
Reserved.
error_payment_url
URL where the customer is redirected when payment is not successful, after returning from an external page, such as a 3DS page. Does not support localhost URLs.
escrow
Details of the escrow for the payment. Relevant when the payment is created with
escrowset to true.amount
The amount in escrow, in units of the currency defined in currency in the payment.
amount_on_hold
Total amount of funds that are currently held in the escrow, in the currency defined in
currency_codein the payment.
created_at
Date and time the escrow was created, in Unix time.
currency
The currency of the escrow balance. Three-letter ISO 4217 code.
escrow_release_days
Indicates the number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated.
escrow_releases
Array of objects that describe individual releases.
ewallets
Array of objects that define the allocation of the release to multiple wallets.
ewallet
ID of the wallet, a string starting with ewallet_.
amount
The amount to release to this wallet. Relevant when
percentageis not set.
percentage
The percentage of this escrow to release to this wallet. Relevant when
amountis not set. On a partial release after the first, this refers to the percentage of the original amount of the escrow.
Note
All wallets in the array must be specified by
amountor bypercentageor neither. If neitheramountnorpercentageis set, the release is proportionate according to the split defined in the payment.
last_payment_completion
Date and time of the completion of the last payment or partial payment, in Unix time.
payment
ID of the payment, a string starting with payment_.
status
Status of the escrow. One of the following:
pending - The payment and escrow were created, but the payment is not completed and the funds are not in the escrow.
on_hold - The payment is completed and the funds are in escrow.
canceled - The escrow is canceled.
released - All or part of the funds have been released to the wallets.
total_amount_released
Total amount of funds that were released to the wallets, in the currency defined in
currency_codein the payment response.
updated_at
Date and time of the last update to the escrow, in Unix time.
escrow_release_days
The number of days after creation of the payment that funds are released from escrow. Funds are released at 5:00 pm GMT on the day indicated.
ewallet_id
ID of the wallet that the money is paid into. String starting with ewallet_.
ewallets
Specifies the wallets that the money is collected into. If this is left blank, the money goes into the oldest collection-type client wallet. If there is no collection client wallet, the money goes into the oldest general-type client wallet.
amount
The amount of the payment to the wallet, in units of the currency defined in
currency.
ewallet_id
ID of the wallet.
percent
The percentage that is paid to the wallet out of the total payment.
refunded_amount
The total amount refunded against this payment, in units of the currency defined in
currency.
expiration
End of the time allowed for the customer to complete this payment, in Unix time.
Note
Relevant to card payments: In some cases, the card networks require a shorter expiration date of the payment. In these cases, the expiration will be updated. Refer to the PAYMENT_COMPLETED webhook to view the updated expiration value.
failure_code
Error code for failure of the payment.
failure_message
Message to the merchant, explaining the reason for failure of the payment.
fixed_side
Indicates whether the FX rate is fixed for the buy side (seller) or for the sell side (buyer).
buy - The currency that the Rapyd Wallet receives for goods or services. Fixed side buy relates to the seller (merchant) funds. For example, a US-based merchant wants to charge 100 USD. The buyer (customer) pays the amount in MXN that converts to 100 USD.
sell - The currency that the buyer is charged for purchasing goods or services. Fixed side sell relates to the buyer (customer) funds. For example, a US-based merchant wants to charge a buyer 2,000 MXN and will accept whatever amount in USD that is converted from 2,000 MXN.
flow_type
Reserved.
fx_rate
Exchange rate for the transaction.
When
fixed_sideis buy,fx_rateis the buy rate.When
fixed_sideis sell,fx_rateis the sell rate.
group_payment
ID of the group payment.
Relevant when the payment is part of a group payment.
id
ID of the payment. String starting with payment_.
initiation_type
Indicates how the transaction was initiated. One of the following:
customer_present - The transaction was initiated by the customer.
installment - The transaction was initiated by a subscription where there is a fixed number of installments.
moto - The transaction was initiated by the merchant or Rapyd client for a mail order or telephone order.
recurring - The transaction was initiated by a subscription where charges are made at regular intervals and there is no end date.
unscheduled - The transaction is a top-up transaction that was previously authorized by the cardholder and was initiated by the merchant or Rapyd client.
instructions
Describes how the customer makes the payment.
name
Description of the payment method.
steps
An array containing a list of steps for the customer to take. Each step is named stepN, where N is an integer.
invoice
ID of the invoice that this payment is for.
is_partial
Indicates whether the payment has been partially paid. When false, indicates that the payment is unpaid or fully paid.
merchant_reference_id
Identifier defined by the client for reference purposes. Limit: 45 characters.
merchant_requested_amount
Indicates the amount paid by the payer, in units of the currency defined in
merchant_requested_currency.Relevant to payments with FX.
merchant_requested_currency
Indicates the currency that merchant receives. Three-letter ISO 4217 code.
Relevant to payments with FX.
metadata
A JSON object defined by the client. See Metadata.
mid
Reserved.
next_action
Indicates the next action for completing the payment. One of the following values:
3d_verification - The next action is 3DS authentication. Relevant only to card payments.
pending_capture - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero.
pending_confirmation - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.
not_applicable - The payment has completed or the next action is not relevant.
order
ID of the order that this payment is for.
original_amount
Payments not involving foreign exchange - The amount of the payment, in units of the currency defined in
currency, including gross transaction fees.Foreign exchange payments - The amount paid by the buyer, in units of the currency defined in
currency_code, including gross transaction fees and gross FX fees.
outcome
Describes the outcome of the risk assessment.
network_status
Network status of the payment. One of the following:
approved_by_network
declined_by_network
not_sent_to_network
reversed_after_approval
risk_level
Assessment of the risk level of the payment. One of the following:
normal
elevated
highest
not_assessed
seller_message
Message to the merchant.
type
Indicates the outcome of the risk assessment. One of the following:
authorized
manual_review
issuer_declined
blocked
invalid
reason
More detailed indication of the reason indicated by
type. One of the following:highest_risk_level - Blocked by default rules.
elevated_risk_level - Placed in review by default rules.
rule - Placed in review by customer-designed rules.
paid
Indicates whether the payment has been fully captured.
paid_at
Time of the last capture, in Unix time.
payment_account_reference
An alphanumeric code that identifies the payment account linked to the card. Appears only in card related responses that use this EMVCo standard value.
payment_fees
Defines transaction fees and foreign exchange fees. These are fees that the Rapyd merchant can define for its consumers in addition to the payment amount. They are not related to the fees Rapyd charges to its clients.
transaction_fee
Describes the fee for processing the transaction.
calc_type
Specifies how the fee is calculated. One of the following:
net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
fee_type
One of the following:
percentage - A percentage of the transaction amount. For example, 5 percent is represented by value=5.
absolute - A fixed amount.
value
The amount of the fee.
fx_fee
Describes the fees for processing the currency exchange. Relevant to payments with FX.
calc_type
Specifies how the fee is calculated. One of the following:
net - The fee is deducted from the amount paid. For example, in a payment of $100 with a fee of 5%, the recipient receives $95.00 and the $5.00 fee goes to the client wallet.
gross - The fee is added to the amount paid. For example, for a transaction of $100 with a fee of 5%, the sender pays $105.00.
value
The amount of the fee. Percentage.
gross_fees
The total gross fees for the transaction, in units defined by
currency_code.
net_fees
The total net fees for the transaction, in units defined by
merchant_requested_currency.
total_merchant_fees
The amount of the fee.
payment_method
Payment method ID.
Note
Card payment method ID is not returned when the
next_actionis 3d_verification or whensave_payment_methodwas set to false.
payment_method_data
Details of the payment method.
account_last4
Last four digits of the IBAN.
Relevant to bank transfers.
acs_check
Results of the Access Control Server (ACS) check. Possible values:
pass
fail
unavailable
unchecked
Relevant to cards.
avs_check
Results of the Address Verification Service (AVS) check.
Relevant to Visa, Mastercard, Amex, and Discover cards.
authentication_url
URL of a page where the customer enters the IBAN and phone number for authentication.
Relevant to some bank transfer payment methods.
bic_swift
BIC (Bank Identifier Code)/SWIFT code.
bin_details
Bank identification details. Relevant to cards.
bin_number
Bank identification number of the issuing bank.
brand
The brand of the card.
country
The country where the card was issued.
issuer
Name of the bank that issued the card.
level
The level of the card.
type
The type of card.
category
Category of payment method. One of the following:
bank_redirect
bank_transfer
card
cardtocard
cash
ewallet
rapyd_ewallet
cvv_check
Verification of the card’s CVV. Valid values:
pass
fail
unavailable
unchecked
Relevant to cards.
digital_wallet
Information about the digital wallet.
pan_type
Describes the type of PAN.
type
Describes the type of digital wallet.
expiration_month
The month when the expiration of the card occurs.
Relevant to cards.
expiration_year
The year when the expiration of the card occurs.
Relevant to cards.
fingerprint_token
Hash of the card number, expiration date and CVV.
Relevant to cards.
id
ID of the payment method.
Note
Card payment method ID is not returned when the
next_actionis 3d_verification or whensave_payment_methodwas set to false.
image
A URL to the image of the icon for the payment method type.
last4
Last four digits of the card.
Relevant to cards.
metadata
A JSON object defined by the client. See Metadata.
network_reference_id
Identifier for use in a recurring card payment.
next_action
Indicates the next action for completing the payment. One of the following values:
3d_verification - The next action is 3DS. Relevant to card payments.
pending_capture - The next action is pending the capture of the amount. Relevant to card payments when the amount is not zero.
pending_confirmation - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.
not_applicable - The payment has completed or the next action is not relevant.
type
Type of the payment card. Possible values:
credit
debit
prepaid
unknown
Relevant to cards.
supporting_documentation
Reserved.
webhook_url
Reserved.
payment_method_options
Object describing additional payment method fields for the payment. These values are not saved as part of the payment method object.
payment_method_type
The type of payment method.
payment_method_type_category
Category of payment method type. One of the following:
bank_redirect
bank_transfer
card
cash
ewallet
rapyd_ewallet
receipt_email
Email address that the receipt for this transaction is sent to.
receipt_number
Reserved.
redirect_url
URL where the customer is redirected for additional steps for the payment.
refunded
Indicates whether there was a refund against this payment.
refunded_amount
The total amount refunded against this payment, in units of the currency defined in
currency.
refunds
An array containing a
dataobject:data
A list of up to three
refundobjects.
has_more
Indicates whether there are more than three refunds against this payment.
total_count
Total number of refunds against this payment.
url
URL for requesting all of the refunds against this payment.
remitter_information
Contains the remitter's name and bank account information. This includes:
account_id
Number of the remitter's bank account.
bank_code
SWIFT code for the remitter's bank.
name
Name of the remitter.
requested_currency
Currency for one side of an FX transaction. Three-letter ISO 4217 code.
When
fixed_sideis sell, it is the currency received in the Rapyd Wallet.When
fixed_sideis buy, it is the currency charged to the buyer (customer).
save_payment_method
Relevant to card payment methods when the request included full card details. Indicates whether Rapyd saved the payment method for future use.
statement_descriptor
A text description suitable for a customer's payment statement. 5-22 characters.
status
Indicates the status of the payment. One of the following:
ACT - Active and awaiting completion of 3DS or capture. Can be updated.
CAN - Canceled by the client or the customer's bank.
CLO - Closed.
ERR - Error. An attempt was made to create or complete a payment, but it failed.
EXP - The payment has expired.
REV - Reversed by Rapyd. See
cancel_reason.
textual_codes
A set of text codes for the customer to use to complete the steps described in the
instructionsfield. The name of the field is the local name of the code, or some other label. For example:codepaycodepayidpairing_codepayment_coderesponse_code
transaction_id
ID of the associated transaction.
visual_codes
A set of images for the customer to use to complete the steps described in the
instructionsfield. For example, a QR code or barcode.
PAYMENT_REVERSED Webhook
{ "id": "wh_3df6fcdc1e85d4e9422bb4c6897b8f50", "data": { "id": "payment_3820149aaec76394930449740f7a2276", "mid": "", "paid": true, "order": null, "amount": 100, "escrow": null, "status": "REV", "address": null, "dispute": null, "fx_rate": 1, "invoice": "", "outcome": null, "paid_at": 1660805397, "refunds": null, "captured": true, "ewallets": [{ "amount": 100, "percent": 100, "ewallet_id": "ewallet_64a88f5456aed969cd6a7e6e5070eb58", "refunded_amount": 0 } ], "metadata": {}, "refunded": false, "auth_code": "064957", "flow_type": "", "created_at": 1660805397, "error_code": "", "ewallet_id": "ewallet_64a88f5456aed969cd6a7e6e5070eb58", "expiration": 1661410197, "fixed_side": "", "is_partial": false, "description": "testing", "next_action": "not_applicable", "country_code": "GB", "failure_code": "", "instructions": [], "payment_fees": null, "redirect_url": "", "visual_codes": {}, "cancel_reason": "insufficient_funds", "currency_code": "USD", "group_payment": "", "receipt_email": "", "textual_codes": {}, "customer_token": "cus_c0984b58200de283b00b0e71b64a92ec", "payment_method": "card_4d939fe7c046ba4d1098f6bfa6771933", "receipt_number": "", "transaction_id": "", "failure_message": "", "initiation_type": "customer_present", "original_amount": 100, "refunded_amount": 0, "error_payment_url": "https://support.rapyd.net/hc/en-us", "payment_method_data": {}, "payment_method_type": "gb_visa_card", "complete_payment_url": "https://www.rapyd.net", "remitter_information": {}, "statement_descriptor": "Rapyd Automation - DO ", "merchant_reference_id": "", "payment_method_options": {}, "merchant_requested_amount": null, "merchant_requested_currency": null, "payment_method_type_category": "card" }, "type": "PAYMENT_REVERSED", "status": "NEW", "created_at": 1660805404, "extended_timestamp": 1660805404145, "trigger_operation_id": "96871a1a-ea41-4eb9-86ae-c85826526a7f" }
The number of seconds elapsed since the beginning of the Unix epoch, which was 00:00:00 GMT on January 1, 1970. 10-digit integer.
A number for a bank account that is used for international transfers.
A server used by issuing banks to authenticate card users by 3DS authentication.
For card transactions, a service that checks whether the cardholder's billing address matches the address for the cardholder's account.
An alphanumeric identifier for financial institutions, also known informally as a SWIFT code or SWIFT/BIC code.
A numeric identifier for financial institutions. It appears as the first four to six digits on a payment card.
A unique number for a payment card, usually 14 to 19 digits in length. Also known as a card number, payment card number or funding primary account number (FPAN).
A numeric code printed on the card, consisting of 3 or 4 digits. Use of the code indicates that the person making the transaction has access to the physical card. This value cannot be stored in any way. Also known as CCV, CID, CSC and CVC.
A protocol that provides increased security for card-not-present transactions. Rapyd supports version 2.2.