skip to Main Content
  • Blog
  • How to Hold and Release an Escrow

How to Hold and Release an Escrow

escrow api

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. 

 

  1. List Wallets or Create a Wallet

  2. Grab the Wallet ID

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

       },

Related Articles

developer looking at computer screen

The 97 Things Every Programmer Should Know – The Rapyd DevTalk Highlights

Read Blog Post
Developer looking at computer screen in dark room

Study Finds Nearly Half of Developers Involved in Data/AI Initiatives, Even More Want To Be

Read Blog Post

Subscribe Via Email

Thank You!

You’ve Been Subscribed.

Back To Top xandr