Developers

How to Hold and Release an Escrow

Simplify your escrow payments with the Rapyd API.

Anyone can use the Rapyd Hosted Checkout Page to receive a payment and hold the funds in escrow for later release after all parties have completed their part of the payment agreement.

An escrow is an arrangement to hold funds in a transaction between two or more parties. Typically the time when the funds are released to the seller is based upon agreed requirements between the parties. For example, once a luxury art piece is delivered, or after the closing of a real estate property deal.

When a payment is made and held in escrow, there are a few ways for the escrow to be released:

Full or partial release on demand.
Release automatically after a specific number of days.
Partial releases can be released by amount or percentage and proportional or non-proportional.

Any developer or merchant collecting an escrow payment without the highest standard of payment card compliance should consider using a secure way of handling sensitive credit card information. The Rapyd Hosted Checkout Page is a way to generate a secure webpage and incorporate it into your user flow. The Hosted Checkout Page can also be embedded directly into your website for a seamless user experience.

The following is an example of how to create a Hosted Checkout Page, accept a payment to hold in escrow and then release the payment.

Note: Before you begin be sure to create your account in the Client Portal, and assign your API keys found in the Developer tab.

List Wallets or Create a Wallet
Grab the Wallet ID
Create Hosted Checkout Page with Escrow

Request

{

“amount”: 11500,

“complete_payment_url”: “http://example.com/complete”,

“country”: “US”,

“currency”: “USD”,

“error_payment_url”: “http://example.com/error”,

“merchant_reference_id”: “merchant-001-0329-2022”,

“payment_method_type”: “us_mastercard_card”,

“ewallets”: [{

“ewallet”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”

}

“escrow”: true,

“escrow_release_days”: “5”,

“metadata”: {

“merchant_defined”: “true”

}

Response

{

“status”: {

“error_code”: “”,

“status”: “SUCCESS”,

“message”: “”,

“response_code”: “”,

“operation_id”: “4652b46d-ef6d-433f-866a-686066b3e9e8”

“data”: {

“id”: “checkout_05203126d8b793472dd3d74c27c05af1”,

“status”: “NEW”,

“language”: null,

“merchant_color”: “323fff”,

“merchant_logo”: null,

“merchant_website”: “http://rapyd.net”,

“merchant_customer_support”: {

“url”: “http://support.rapyd.net”,

“email”: “support@rapyd.net”,

“phone_number”: “555-555-5555”

“merchant_alias”: “Test Business”,

“merchant_terms”: null,

“merchant_privacy_policy”: null,

“page_expiration”: 1649861537,

“redirect_url”: “https://sandboxcheckout.rapyd.net?token=checkout_05203126d8b793472dd3d74c27c05af1”,

“region”: null,

“geo_country”: null,

“merchant_main_button”: “place_your_order”,

“cancel_checkout_url”: “http://rapyd.net”,

“complete_checkout_url”: “http://rapyd.net”,

“country”: “US”,

“currency”: “USD”,

“amount”: 11500,

“payment”: {

“id”: null,

“amount”: 11500,

“original_amount”: 0,

“is_partial”: false,

“currency_code”: “USD”,

“country_code”: “US”,

“status”: null,

“description”: “Payment via Checkout”,

“merchant_reference_id”: “merchant-001-0329-2022”,

“customer_token”: null,

“payment_method”: null,

“payment_method_data”: {},

“expiration”: 0,

“captured”: false,

“refunded”: false,

“refunded_amount”: 0,

“receipt_email”: null,

“redirect_url”: null,

“complete_payment_url”: “http://example.com/complete”,

“error_payment_url”: “http://example.com/error”,

“receipt_number”: null,

“flow_type”: null,

“address”: null,

“statement_descriptor”: null,

“transaction_id”: null,

“created_at”: 0,

“updated_at”: 0,

“metadata”: {

“merchant_defined”: “true”

“failure_code”: null,

“failure_message”: null,

“paid”: false,

“paid_at”: 0,

“dispute”: null,

“refunds”: null,

“order”: null,

“outcome”: null,

“visual_codes”: {},

“textual_codes”: {},

“instructions”: {},

“ewallets”: [

{

“ewallet”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“amount”: 11500,

“percent”: 100

}

“payment_method_options”: {},

“payment_method_type”: null,

“payment_method_type_category”: null,

“fx_rate”: null,

“merchant_requested_currency”: null,

“merchant_requested_amount”: null,

“fixed_side”: null,

“payment_fees”: null,

“invoice”: null,

“escrow”: null,

“group_payment”: null,

“cancel_reason”: null,

“initiation_type”: “customer_present”,

“mid”: null,

“next_action”: “not_applicable”

“payment_method_type”: null,

“payment_method_type_categories”: null,

“payment_method_types_include”: null,

“payment_method_types_exclude”: null,

“customer”: null,

“custom_elements”: {

“save_card_default”: false,

“display_description”: false,

“payment_fees_display”: true,

“merchant_currency_only”: false,

“billing_address_collect”: false,

“dynamic_currency_conversion”: false

“timestamp”: 1648651937,

“payment_expiration”: null,

“cart_items”: [],

“escrow”: true,

“escrow_release_days”: 5

}

4. Complete Purchase

Since the payment method is an ACH bank transfer, a request is made to complete the purchase.

Request

{

“token”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“param2”: “11500”

}

Response

{

“id”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“amount”: 11500,

“original_amount”: 11500,

“is_partial”: false,

“currency_code”: “USD”,

“country_code”: “US”,

“status”: “CLO”,

“description”: “Payment via Checkout”,

“merchant_reference_id”: “merchant-001-0329-2022”,

“customer_token”: “cus_0ffe4d0cd2bbec4cbc21a09feb21af17”,

“payment_method”: “other_e43cde84d6d90177595085f3f2da29f9”,

“payment_method_data”: {

“id”: “other_e43cde84d6d90177595085f3f2da29f9”,

“type”: “us_ach_bank”,

“category”: “bank_transfer”,

“metadata”: {},

“image”: “”,

“webhook_url”: “”,

“supporting_documentation”: “”,

“next_action”: “not_applicable”,

“account_number”: “856677”,

“routing_number”: “072403006”,

“payment_purpose”: “high end purchase art”,

“proof_of_authorization”: true

// …

“ewallet_id”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“ewallets”: [

{

“ewallet_id”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“amount”: 11500,

“percent”: 100,

“released_amount”: 0,

“refunded_amount”: 0

}

“payment_method_options”: {},

“payment_method_type”: “us_ach_bank”,

“payment_method_type_category”: “bank_transfer”,

“fx_rate”: 1,

…

“escrow”: {

“id”: “escrow_aa294224e702132b3a03b585b9a6d494”,

“payment”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“amount_on_hold”: 11500,

“total_amount_released”: 0,

“status”: “on_hold”,

“escrow_release_days”: 5,

“created_at”: 1648653731,

“updated_at”: 1648653731,

“last_payment_completion”: 1648654127

}

Release Escrow with Payment ID and Escrow ID

You request a manual release with the payment ID starting with payment_ and escrow ID starting with escrow_.

Response

{

“status”: {

“error_code”: “”,

“status”: “SUCCESS”,

“message”: “”,

“response_code”: “”,

“operation_id”: “b148dfd0-0d6c-4945-9294-34e66371afa7”

“data”: {

“id”: “escrow_aa294224e702132b3a03b585b9a6d494”,

“payment”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“amount_on_hold”: 0,

“total_amount_released”: 11500,

“status”: “released”,

“escrow_release_days”: 5,

“escrow_releases”: {

“data”: [

{

“id”: “er_bd5f642ba700de81a11bf0e38b42147e”,

“amount”: 11500,

“trigger”: “event”,

“proportional_release”: true,

“ewallets”: [

{

“ewallet”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“amount”: 11500

}

“created_at”: 1648672959

}

“has_more”: false,

“total_count”: 1,

“url”: “/v1/payments/payment_16045deca20b92a9aae1fe17ed506f69/escrows/escrow_aa294224e702132b3a03b585b9a6d494/escrow_releases”

“created_at”: 1648653731,

“updated_at”: 1648672959,

“last_payment_completion”: 1648654127

}

Note: When the funds are released, Rapyd notifies you via webhook that the transfer was completed successfully.

You can start testing now with Rapyd and the guide: Get Started and make your first API call.

Sources

Photo by Scott Graham Unsplash

Stop

List Payments

{

“status”: {

“error_code”: “”,

“status”: “SUCCESS”,

“message”: “”,

“response_code”: “”,

“operation_id”: “2a538d36-db4f-46e4-940f-f1c9c7e6806b”

“data”: [

{

“id”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“amount”: 0,

“original_amount”: 11500,

“is_partial”: false,

“currency_code”: “USD”,

“country_code”: “US”,

“status”: “ACT”,

“description”: “Payment via Checkout”,

“merchant_reference_id”: “merchant-001-0329-2022”,

“customer_token”: “cus_0ffe4d0cd2bbec4cbc21a09feb21af17”,

“payment_method”: “other_e43cde84d6d90177595085f3f2da29f9”,

“payment_method_data”: {

“id”: “other_e43cde84d6d90177595085f3f2da29f9”,

“type”: “us_ach_bank”,

“category”: “bank_transfer”,

“metadata”: {},

“image”: “”,

“webhook_url”: “”,

“supporting_documentation”: “”,

“next_action”: “not_applicable”,

“account_number”: “856677”,

“routing_number”: “072403006”,

“payment_purpose”: “high end purchase art”,

“proof_of_authorization”: true

“expiration”: 1649863331,

“captured”: true,

“refunded”: false,

“refunded_amount”: 0,

“receipt_email”: “”,

“redirect_url”: “”,

“complete_payment_url”: “http://example.com/complete”,

“error_payment_url”: “http://example.com/error”,

“receipt_number”: “”,

“flow_type”: “”,

“address”: null,

“statement_descriptor”: “Test Business”,

“transaction_id”: “”,

“created_at”: 1648653731,

“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”: {

“name”: “instructions”,

“steps”: [

{

“step1”: “Provide your routing and account number to process the transaction”

{

“step2”: “Once completed, the transaction will take approximately 2-3 days to process”

}

]

“ewallet_id”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“ewallets”: [

{

“ewallet_id”: “ewallet_db4ad4a76278f94c4a83dd9b28b483ed”,

“amount”: 11500,

“percent”: 100,

“released_amount”: 0,

“refunded_amount”: 0

}

“payment_method_options”: {},

“payment_method_type”: “us_ach_bank”,

“payment_method_type_category”: “bank_transfer”,

“fx_rate”: 1,

“merchant_requested_currency”: null,

“merchant_requested_amount”: null,

“fixed_side”: “”,

“payment_fees”: null,

“invoice”: “”,

“escrow”: {

“id”: “escrow_aa294224e702132b3a03b585b9a6d494”,

“payment”: “payment_16045deca20b92a9aae1fe17ed506f69”,

“amount_on_hold”: 0,

“total_amount_released”: 0,

“status”: “pending”,

“escrow_release_days”: 5,

“created_at”: 1648653731,

“updated_at”: 1648653731,

“last_payment_completion”: null

“group_payment”: “”,

“cancel_reason”: null,

“initiation_type”: “customer_present”,

“mid”: “”,

“next_action”: “pending_confirmation”,

“error_code”: “”,

“remitter_information”: {}

Kyle Pollock

Kyle Pollock is a Technical and UX Content Writer with 10 years of creating brand content on digital marketing platforms across multiple industries including banking, fintech, non-profit, and public health. Kyle wants to improve how global fintech developers share information and resources to build powerful tools. Kyle is passionate about equipping others to solve challenging problems, and shaping meaningful customer experiences to drive business growth.