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

Mark Stiltner

Mark Stiltner is a finance and fintech writer. From educating independent investment advisors on retirement plan management to helping families maximize their savings to educating businesses on global payment preferences, Mark has spent over a decade researching and educating audiences on complex financial topics. Mark has been a contributing author on blog articles and educational content for the Bank of Colorado, Pinnacle Bank, TD Ameritrade, First Data and Rapyd.