# Payments Webhooks ## Overview Ryft provides several webhook events related to **payments** that allow you to stay informed about the status and lifecycle of payments in your account. These webhooks can be used to automate workflows, update your database, or trigger other actions in your system. Please note these events cover both **online** and **in-person** payments, ensuring you have comprehensive coverage of all payment activities. ## Payment Events These events are related to the lifecycle of a payment session, including its creation, approval, capture, decline, and voiding. We highly recommend using these webhooks, to ensure that your system is always up-to-date with the latest information about payments. Please note the `paymentMethod` field is only supplied when the payment session is created using a saved payment method. PaymentSession.captured This event is triggered when a payment session has been successfully captured. This indicates that the payment has been completed and funds have been secured. ```json PaymentSession.captured - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.captured", "data": { "id": "ps_XXXXXXXX", "amount": 10000, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": false, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "wallet": {"type": "GooglePay"}, "billingAddress": { "firstName": "Card", "lastName": "Name", "lineOne": "1600 Amphitheatre Parkway", "city": "Mountain View", "country": "US", "postalCode": "94043", "region": "CA", }, "checks": {"avsResponseCode": "C", "cvvResponseCode": "P"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "Captured", "refundedAmount": 0, "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Manual", "createdTimestamp": 1759478781, "lastUpdatedTimestamp": 1759479339, "paymentTransactionId": "txn_XXXXXXXX", "customer": {"id": "cus_XXXXXXXX"}, "subscription": {"id": "sub_XXXXXXX"}, // Only for Subscription payments }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759479339, "lastUpdatedTimestamp": 1759479339, "deliveryStatus": "Success", } ``` PaymentSession.capture_failed This event is triggered when a capture attempt for a payment session has failed. This indicates that the payment is not completed, and no funds were captured. ```json PaymentSession.capture_failed - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.capture_failed", "data": { "id": "ps_XXXXXXXX", "amount": 10000, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": false, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "wallet": {"type": "GooglePay"}, "billingAddress": { "firstName": "Card", "lastName": "Name", "lineOne": "1600 Amphitheatre Parkway", "city": "Mountain View", "country": "US", "postalCode": "94043", "region": "CA", }, "checks": {"avsResponseCode": "C", "cvvResponseCode": "P"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "Approved", "refundedAmount": 0, "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Manual", "createdTimestamp": 1759478781, "lastUpdatedTimestamp": 1759478828, "paymentTransactionId": "txn_XXXXXXXX", "customer": {"id": "cus_XXXXXXXX"}, "subscription": {"id": "sub_XXXXXXX"}, // Only for Subscription payments }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759478849, "lastUpdatedTimestamp": 1759478849, "deliveryStatus": "Success", } ``` PaymentSession.approved This event is triggered when a payment session has been approved. This indicates that the payment has been authorized by the customer's bank and is ready to be captured. ```json PaymentSession.approved - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.approved", "data": { "id": "ps_XXXXXXXX", "amount": 10000, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": false, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "wallet": {"type": "GooglePay"}, "billingAddress": { "firstName": "Card", "lastName": "Name", "lineOne": "1600 Amphitheatre Parkway", "city": "Mountain View", "country": "US", "postalCode": "94043", "region": "CA", }, "checks": {"avsResponseCode": "C", "cvvResponseCode": "P"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "Approved", "refundedAmount": 0, "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Manual", "createdTimestamp": 1759478781, "lastUpdatedTimestamp": 1759478828, "paymentTransactionId": "txn_XXXXXXXX", "customer": {"id": "cus_XXXXXXXX"}, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759478849, "lastUpdatedTimestamp": 1759478849, "deliveryStatus": "Success", } ``` PaymentSession.declined This event is triggered when a payment session has been declined. This indicates that the payment attempt was unsuccessful, and no funds were captured. Check the `lastError` field in the payment session object for more details. ```json PaymentSession.declined - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.declined", "data": { "id": "ps_XXXXXXXX", "amount": 315, "currency": "GBP", "paymentType": "Recurring", "entryMode": "Online", "rebillingDetail": { "amountVariance": "Variable", "numberOfDaysBetweenPayments": 28, "totalNumberOfPayments": 6, "currentPaymentNumber": 1, "expiry": 1777075199, }, "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": true, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "PendingPayment", "metadata": { "customerId": "147", "basketId": "10966", "customerName": "TestName", }, "refundedAmount": 0, "lastError": "3ds_authentication_failure", "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Automatic", "createdTimestamp": 1758790566, "lastUpdatedTimestamp": 1758790567, "customer": {"id": "cus_XXXXXXXX"}, "subscription": {"id": "sub_XXXXXXXX"}, // Only for Subscription payments }, "createdTimestamp": 1758790568, "lastUpdatedTimestamp": 1758790568, "deliveryStatus": "None", } ``` PaymentSession.voided This event is triggered when a payment session has been voided. This indicates that the authorization for the payment has been cancelled, and no funds will be captured. ```json PaymentSession.voided - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.voided", "data": { "id": "ps_XXXXXXXX", "amount": 10000, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": false, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "wallet": {"type": "GooglePay"}, "billingAddress": { "firstName": "Card", "lastName": "Name", "lineOne": "1600 Amphitheatre Parkway", "city": "Mountain View", "country": "US", "postalCode": "94043", "region": "CA", }, "checks": {"avsResponseCode": "C", "cvvResponseCode": "P"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "Voided", "refundedAmount": 0, "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Manual", "createdTimestamp": 1759478781, "lastUpdatedTimestamp": 1759478828, "paymentTransactionId": "txn_XXXXXXXX", "customer": {"id": "cus_XXXXXXXX"}, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759478849, "lastUpdatedTimestamp": 1759478849, "deliveryStatus": "Success", } ``` PaymentSession.void_failed This event is triggered when a void attempt for a payment session has failed. This indicates that the void process was unsuccessful, and the funds are still on hold with the customer's bank. ```json PaymentSession.void_failed - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.void_failed", "data": { "id": "ps_XXXXXXXX", "amount": 10000, "currency": "GBP", "paymentType": "Standard", "entryMode": "Online", "customerEmail": "test@gmail.com", "customerDetails": {"id": "cus_XXXXXXXX"}, "enabledPaymentMethods": ["Card"], "paymentMethod": { "type": "Card", "tokenizedDetails": { "id": "pmt_XXXXXXXX", "stored": false, }, "card": {"scheme": "Visa", "last4": "XXXX"}, "wallet": {"type": "GooglePay"}, "billingAddress": { "firstName": "Card", "lastName": "Name", "lineOne": "1600 Amphitheatre Parkway", "city": "Mountain View", "country": "US", "postalCode": "94043", "region": "CA", }, "checks": {"avsResponseCode": "C", "cvvResponseCode": "P"}, "id": "pmt_XXXXXXXX", }, "returnUrl": "https://test.com", "status": "Approved", "refundedAmount": 0, "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}, "authorizationType": "FinalAuth", "captureFlow": "Manual", "createdTimestamp": 1759478781, "lastUpdatedTimestamp": 1759478828, "paymentTransactionId": "txn_XXXXXXXX", "customer": {"id": "cus_XXXXXXXX"}, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759478849, "lastUpdatedTimestamp": 1759478849, "deliveryStatus": "Success", } ``` ## Platform Fee Events These events are related to Payments of type [Platform Fee](/documentation/overview/payment_types/platform_fee_split_payments#platform-fee). PlatformFee.created This event is triggered when a Payment of type Platform Fee is created. ```json PlatformFee.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PlatformFee.created", "data": { "id": "pf_XXXXXXXX", "paymentSessionId":"ps_XXXXXXXX", "amount": 500, "processingFee":47, "refundedAmount":0, "netAmount":-37, "currency":"GBP", "fromAccountId":"ac_XXXXXXXX", "createdTimestamp":1759402743, }, "createdTimestamp": 1570989538, } ``` PlatformFee.refunded This event is triggered when a Payment of type Platform Fee is refunded. ```json PlatformFee.refunded - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PlatformFee.refunded", "data": { "id": "pf_XXXXXXXX", "paymentSessionId":"ps_XXXXXXXX", "amount": 500, "processingFee":47, "refundedAmount":500, "netAmount":-37, "currency":"GBP", "fromAccountId":"ac_XXXXXXXX", "createdTimestamp":1759402743, }, "createdTimestamp": 1570989538, } ``` ## Transfer Events These events are related to the transfer of funds between a Main Account and a sub-Account when using the [Transfer API](/documentation/overview/payment_types/transfer), including successful transfers and failed transfer attempts. Transfer.created This event is triggered when a transfer between accounts has been created. This indicates that funds are being moved from one account to another. ```json Transfer.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Transfer.created", "data": { "id": "tfr_XXXXXXXX", "status": "Pending", "amount": 1000, "currency": "GBP", "reason": "Transfer test", "destination": {"accountId": "ac_XXXXXXXX"}, "createdTimestamp": 1759483719, "lastUpdatedTimestamp": 1759483719, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759483719, "lastUpdatedTimestamp": 1759483719, "deliveryStatus": "Success", } ``` Transfer.updated This event is triggered when a transfer between accounts has been updated. This indicates a change in the status of the transfer, such as `Completed` or `Failed`. ```json Transfer.updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Transfer.updated", "data": { "id": "tfr_XXXXXXXX", "status": "Completed", "amount": 1000, "currency": "GBP", "reason": "Transfer test", "destination": {"accountId": "ac_XXXXXXXX"}, "createdTimestamp": 1759483719, "lastUpdatedTimestamp": 1759483728, }, "accountId": "ac_XXXXXXXX", "createdTimestamp": 1759483728, "lastUpdatedTimestamp": 1759483728, "deliveryStatus": "Success", } ``` ## Refund Events These events are related to the refund process of a payment session, including successful refunds and failed refund attempts. PaymentSession.refunded This event is triggered when a payment session has been refunded. This indicates that the funds from a previously captured payment will be returned to the customer. ```json PaymentSession.refunded - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.refunded", "data": { "id": "ps_XXXXXXXX", "amount": 500, "platformFee": 50, "currency": "GBP", "metadata": {"customerId": "123"}, }, "createdTimestamp": 1570989538, } ``` PaymentSession.refund_failed This event is triggered when a refund attempt for a payment session has failed. This indicates that the refund process was unsuccessful, and the funds will not be returned to the customer. ```json PaymentSession.refund_failed - Payload Example { "id": "ev_XXXXXXXX", "eventType": "PaymentSession.refund_failed", "data": { "id": "ps_XXXXXXXX", "amount": 500, "platformFee": 50, "currency": "GBP", "metadata": {"customerId": "123"}, }, "createdTimestamp": 1570989538, } ``` ## Customer Events These events are related to the lifecycle of a customer, including their creation, updates, and deletion. Customer.created This event is triggered when a customer is created in your Ryft account. ```json Customer.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Customer.created", "data": { "id": "cus_XXXXXXXX", "email": "example@mail.com", "firstName": "Fred", "lastName": "Jones", "metadata": {"customerId": "ef8995ce-ed5c-4f77-b04e-df86de5c11b8"}, "createdTimestamp": 1659538083, }, "createdTimestamp": 1659538083, } ``` Customer.updated This event is triggered when a customer is updated in your Ryft account. ```json Customer.updated - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Customer.updated", "data": { "id": "cus_XXXXXXXX", "email": "a_new_example@mail.com", "firstName": "Fred", "lastName": "Jones", "metadata": {"customerId": "ef8995ce-ed5c-4f77-b04e-df86de5c11b8"}, "defaultPaymentMethod": "pmt_XXXXXXXX", "createdTimestamp": 1659538083, }, "createdTimestamp": 1659538083, } ``` Customer.deleted This event is triggered when a customer is deleted from your Ryft account. ```json Customer.deleted - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Customer.deleted", "data": { "id": "cus_XXXXXXXX", "email": "example@mail.com", "firstName": "Fred", "lastName": "Jones", "metadata": {"customerId": "ef8995ce-ed5c-4f77-b04e-df86de5c11b8"}, "createdTimestamp": 1659538083, }, "createdTimestamp": 1659538083, } ``` ## Dispute Events These events are related to the lifecycle of a dispute, including its creation, challenge, and closure. Dispute.created This event is triggered when a dispute is created for a payment in your Ryft account. ```json Dispute.created - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Dispute.created", "data": { "id": "dsp_XXXXXXXX", "amount": 4531, "currency": "GBP", "status": "Open", "category": "Fraudulent", "reason": { "code": "10.1", "description": "EMV Liability Shift Counterfeit Fraud", }, "respondBy": 1761091200, "recommendedEvidence": [ "Receipt", "ShippingConfirmation", "ProofOfDelivery", "CustomerCommunication", "CustomerSignature", ], "paymentSession": { "id": "ps_XXXXXXXX", "paymentType": "Standard", "paymentMethod": {"card": {"scheme": "Visa", "last4": "XXXX"}}, }, "evidence": { "text": { "billingAddress": "Card Name, 1600 Amphitheatre Parkway, Mountain View, 94043, US, CA" } }, "customer": { "email": "test@gmail.com", "id": "cus_XXXXXXXX", "createdTimestamp": 1757409127, }, "createdTimestamp": 1758729431, "lastUpdatedTimestamp": 1758729431, }, "createdTimestamp": 1758729432, "lastUpdatedTimestamp": 1758729432, "deliveryStatus": "None", } ``` Dispute.challenged This event is triggered when you have successfully challenged a dispute in your Ryft account. ```json Dispute.challenged - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Dispute.challenged", "data": { "id": "dsp_XXXXXXXX", "amount": 4531, "currency": "GBP", "status": "Challenged", "category": "Fraudulent", "reason": { "code": "10.1", "description": "EMV Liability Shift Counterfeit Fraud", }, "respondBy": 1761091200, "recommendedEvidence": [ "Receipt", "ShippingConfirmation", "ProofOfDelivery", "CustomerCommunication", "CustomerSignature", ], "paymentSession": { "id": "ps_XXXXXXXX", "paymentType": "Standard", "paymentMethod": {"card": {"scheme": "Visa", "last4": "XXXX"}}, }, "evidence": { "text": { "billingAddress": "Card Name, 1600 Amphitheatre Parkway, Mountain View, 94043, US, CA" } }, "customer": { "email": "test@gmail.com", "id": "cus_XXXXXXXX", "createdTimestamp": 1757409127, }, "createdTimestamp": 1758729431, "lastUpdatedTimestamp": 1758731557, }, "createdTimestamp": 1758731560, "lastUpdatedTimestamp": 1758731560, "deliveryStatus": "None", } ``` Dispute.closed This event is triggered when a dispute is closed in your Ryft account. This indicates that the dispute has been resolved, either in your favor or the customer's favor. You can check the `status` field in the dispute object to see the outcome of the dispute: - `Expired`: The dispute was not responded to in time and has been automatically closed. It cannot be challenged and the funds have been returned to the customer. - `Lost`: The dispute was challenged but the decision was in favor of the customer. The funds have been returned to the customer. - `Won`: The dispute was challenged and the decision was in your favor. The funds have been returned to you. ```json Dispute.closed - Payload Example { "id": "ev_XXXXXXXX", "eventType": "Dispute.closed", "data": { "id": "dsp_XXXXXXXX", "amount": 500, "currency": "GBP", "status": "Won", "category": "Fraudulent", "reason": {"code": "13.6", "description": "Merchandise/Services Not Received"}, "respondBy": 1685059200, "recommendedEvidence": ["ProofOfDelivery"], "paymentSession": { "id": "ps_XXXXXXXX", "paymentType": "Standard", "paymentMethod": {"card": {"scheme": "Mastercard", "last4": "XXXX"}}, }, "evidence": { "files": {"proofOfDelivery": {"id": "fl_XXXXXXXX"}}, }, "customer": { "email": "example@mail.com", "id": "cus_XXXXXXXX", "createdTimestamp": 1470989538, }, "createdTimestamp": 1470989538, "lastUpdatedTimestamp": 1470989538, }, "createdTimestamp": 1659538083, } ```