Creating an escrow takes main steps, processing the escrow payment and then releasing the escrow payment. You can learn more about these steps at Managing an Escrow.
The first request will be a Create Payment request via API.
The payment uses a redirect, so there will be a payment created webhook with status as active (ACT) and then a payment completed webhook response with a status as closed (CLO). This is a simulation of the third party payment verification when the customer signs into their bank to complete the payment.
The next request will be release an escrow, and a final API response will show as status: released.
Create Payment with Escrow
Endpoint
post https://sandboxapi.rapyd.net/v1/payments
Request
"amount": 7000,
"currency": "SGD",
"complete_payment_url": "https://rapyd.net",
"error_payment_url": "https://docs.rapyd.net",
"description": "Payment by bank redirect",
"escrow": true,
"payment_method": {
"type": "sg_ocbcpao_bank",
"fields": {
"app_id":"222222",
"url_scheme":"https://rapyd.net"
}
},
"capture": null,
"ewallets": [
{
"ewallet": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"percentage": 100
}
],
"metadata": {
"merchant_defined": true
}
}```
### Response
```{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "fa6b85de-4278-484a-be2c-706d8d916298"
},
"data": {
"id": "payment_517693a9628d9ab0a4439553ff7fda30",
"amount": 0,
"original_amount": 7000,
"is_partial": false,
"currency_code": "SGD",
"country_code": "SG",
"status": "ACT",
"description": "Payment by bank redirect",
"merchant_reference_id": "",
"customer_token": "cus_8f7a913777de078e6a215603ce53a41c",
"payment_method": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"payment_method_data": {
"id": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"type": "sg_ocbcpao_bank",
"category": "bank_redirect",
"metadata": {},
"image": "",
"webhook_url": "",
"supporting_documentation": "",
"next_action": "not_applicable",
"bic_swift": "",
"account_last4": "",
"app_id": "222222",
"url_scheme": "https://rapyd.net"
},
"auth_code": null,
"expiration": 1695340253,
"captured": true,
"refunded": false,
"refunded_amount": 0,
"receipt_email": "",
"redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_517693a9628d9ab0a4439553ff7fda30&complete_payment_url=https%3A%2F%2Frapyd.net&error_payment_url=https%3A%2F%2Fdocs.rapyd.net",
"complete_payment_url": "https://rapyd.net",
"error_payment_url": "https://docs.rapyd.net",
"receipt_number": "",
"flow_type": "",
"address": null,
"statement_descriptor": "Test Business",
"transaction_id": "",
"created_at": 1694130653,
"metadata": {
"merchant_defined": true
},
"failure_code": "",
"failure_message": "",
"paid": false,
"paid_at": 0,
"dispute": null,
"refunds": null,
"order": null,
"outcome": null,
"visual_codes": {},
"textual_codes": {},
"instructions": [
{}
],
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"ewallets": [
{
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"amount": 7000,
"percent": 100,
"refunded_amount": 0
}
],
"payment_method_options": {},
"payment_method_type": "sg_ocbcpao_bank",
"payment_method_type_category": "bank_redirect",
"fx_rate": 1,
"merchant_requested_currency": null,
"merchant_requested_amount": null,
"fixed_side": "",
"payment_fees": null,
"invoice": "",
"escrow": {
"id": "escrow_035af3d6e55808642ac38e03f02b1d62",
"payment": "payment_517693a9628d9ab0a4439553ff7fda30",
"currency": "SGD",
"amount_on_hold": 0,
"total_amount_released": 0,
"status": "pending",
"escrow_release_days": null,
"created_at": 1694130653,
"updated_at": 1694130653,
"last_payment_completion": null
},
"group_payment": "",
"cancel_reason": null,
"initiation_type": "customer_present",
"mid": "",
"next_action": "pending_confirmation",
"error_code": "",
"remitter_information": {},
"save_payment_method": true
}
}
Webhook
"id": "wh_650730b49d5f894ef4e6bd0a8a1f1262",
"type": "PAYMENT_SUCCEEDED",
"data": {
"id": "payment_517693a9628d9ab0a4439553ff7fda30",
"mid": "",
"paid": false,
"order": null,
"amount": 0,
"escrow": {
"id": "escrow_035af3d6e55808642ac38e03f02b1d62",
"status": "pending",
"payment": "payment_517693a9628d9ab0a4439553ff7fda30",
"currency": "SGD",
"created_at": 1694130653,
"updated_at": 1694130653,
"amount_on_hold": 0,
"escrow_release_days": null,
"total_amount_released": 0,
"last_payment_completion": null
},
"status": "ACT",
"address": null,
"dispute": null,
"fx_rate": 1,
"invoice": "",
"outcome": null,
"paid_at": 0,
"refunds": null,
"captured": true,
"ewallets": [
{
"amount": 7000,
"percent": 100,
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"refunded_amount": 0
}
],
"metadata": {
"merchant_defined": true
},
"refunded": false,
"auth_code": null,
"flow_type": "",
"created_at": 1694130653,
"error_code": "",
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"expiration": 1695340253,
"fixed_side": "",
"is_partial": false,
"description": "Payment by bank redirect",
"next_action": "pending_confirmation",
"country_code": "SG",
"failure_code": "",
"instructions": [
{}
],
"payment_fees": null,
"redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_517693a9628d9ab0a4439553ff7fda30&complete_payment_url=https%3A%2F%2Frapyd.net&error_payment_url=https%3A%2F%2Fdocs.rapyd.net",
"visual_codes": {},
"cancel_reason": null,
"currency_code": "SGD",
"group_payment": "",
"receipt_email": "",
"textual_codes": {},
"customer_token": "cus_8f7a913777de078e6a215603ce53a41c",
"payment_method": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"receipt_number": "",
"transaction_id": "",
"failure_message": "",
"initiation_type": "customer_present",
"original_amount": 7000,
"refunded_amount": 0,
"error_payment_url": "https://docs.rapyd.net",
"payment_method_data": {
"id": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"type": "sg_ocbcpao_bank",
"image": "",
"app_id": "222222",
"category": "bank_redirect",
"metadata": {},
"bic_swift": "",
"url_scheme": "https://rapyd.net",
"next_action": "not_applicable",
"webhook_url": "",
"account_last4": "",
"supporting_documentation": ""
},
"payment_method_type": "sg_ocbcpao_bank",
"save_payment_method": true,
"complete_payment_url": "https://rapyd.net",
"remitter_information": {},
"statement_descriptor": "Test Business",
"merchant_reference_id": "",
"payment_method_options": {},
"merchant_requested_amount": null,
"merchant_requested_currency": null,
"payment_method_type_category": "bank_redirect"
},
"trigger_operation_id": "fa6b85de-4278-484a-be2c-706d8d916298",
"status": "NEW",
"created_at": 1694130653
}
Now you can complete the bank redirect payment
Webhook Payment Completed
{
"id": "wh_28a9418b507ff28dc9115bb7038e284e",
"type": "PAYMENT_COMPLETED",
"data": {
"id": "payment_517693a9628d9ab0a4439553ff7fda30",
"mid": "",
"paid": true,
"order": null,
"amount": 7000,
"escrow": {
"id": "escrow_035af3d6e55808642ac38e03f02b1d62",
"status": "on_hold",
"payment": "payment_517693a9628d9ab0a4439553ff7fda30",
"currency": "SGD",
"created_at": 1694130653,
"updated_at": 1694130653,
"amount_on_hold": 7000,
"escrow_release_days": null,
"total_amount_released": 0,
"last_payment_completion": 1694130752
},
"status": "CLO",
"address": null,
"dispute": null,
"fx_rate": 1,
"invoice": "",
"outcome": null,
"paid_at": 1694130752,
"refunds": null,
"captured": true,
"ewallets": [
{
"amount": 7000,
"percent": 100,
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"refunded_amount": 0,
"released_amount": 0
}
],
"metadata": {
"merchant_defined": true
},
"refunded": false,
"auth_code": null,
"flow_type": "",
"created_at": 1694130653,
"error_code": "",
"ewallet_id": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"expiration": 1695340253,
"fixed_side": "",
"is_partial": false,
"description": "Payment by bank redirect",
"next_action": "not_applicable",
"country_code": "SG",
"failure_code": "",
"instructions": [
{}
],
"payment_fees": null,
"redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_517693a9628d9ab0a4439553ff7fda30&complete_payment_url=https%3A%2F%2Frapyd.net&error_payment_url=https%3A%2F%2Fdocs.rapyd.net",
"visual_codes": {},
"cancel_reason": null,
"currency_code": "SGD",
"group_payment": "",
"receipt_email": "",
"textual_codes": {},
"customer_token": "cus_8f7a913777de078e6a215603ce53a41c",
"payment_method": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"receipt_number": "",
"transaction_id": "",
"failure_message": "",
"initiation_type": "customer_present",
"original_amount": 7000,
"refunded_amount": 0,
"error_payment_url": "https://docs.rapyd.net",
"payment_method_data": {
"id": "other_cec13f96225f0ab88c341d7cf7de4f7d",
"type": "sg_ocbcpao_bank",
"image": "",
"app_id": "222222",
"category": "bank_redirect",
"metadata": {},
"bic_swift": "",
"url_scheme": "https://rapyd.net",
"next_action": "not_applicable",
"webhook_url": "",
"account_last4": "",
"supporting_documentation": ""
},
"payment_method_type": "sg_ocbcpao_bank",
"save_payment_method": true,
"complete_payment_url": "https://rapyd.net",
"remitter_information": {},
"statement_descriptor": "Test Business",
"merchant_reference_id": "",
"payment_method_options": {},
"merchant_requested_amount": null,
"merchant_requested_currency": null,
"payment_method_type_category": "bank_redirect"
},
"trigger_operation_id": "d5bc9747-8f4e-488b-8a84-7445d7c01baa",
"status": "NEW",
"created_at": 1694130752
}
Release Escrow
Endpoint
post https://sandboxapi.rapyd.net/v1/payments/:payment/escrows/:escrow/escrow_releases
Path Variables
payment:payment_517693a9628d9ab0a4439553ff7fda30
escrow:escrow_035af3d6e55808642ac38e03f02b1d62
Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "edeacc9e-fb19-40da-9ec1-e66b570a872d"
},
"data": {
"id": "escrow_035af3d6e55808642ac38e03f02b1d62",
"payment": "payment_517693a9628d9ab0a4439553ff7fda30",
"currency": "SGD",
"amount_on_hold": 0,
"total_amount_released": 7000,
"status": "released",
"escrow_release_days": null,
"escrow_releases": {
"data": [
{
"id": "er_55519844a75641599f34079aad3570ea",
"amount": 7000,
"trigger": "event",
"proportional_release": true,
"ewallets": [
{
"ewallet": "ewallet_9fe982e2fa785bd1edba7e83154b3663",
"amount": 7000
}
],
"created_at": 1694130802,
"currency": "SGD"
}
],
"has_more": false,
"total_count": 1,
"url": "/v1/payments/payment_517693a9628d9ab0a4439553ff7fda30/escrows/escrow_035af3d6e55808642ac38e03f02b1d62/escrow_releases"
},
"created_at": 1694130653,
"updated_at": 1694130802,
"last_payment_completion": 1694130752
}
}