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

       },

Chart: Guide To Marketplace Payment Processing
Guide to Marketplace Payment Processing
Read Blog Post
Tiki Lobel, Rapyd R&D Engineering Team Lead, Presenting 'How To Become A Fintech Developer In Seven Minutes' At The Summit
How To Become A Fintech Developer In Seven Minutes And Embed Financial Services Into Applications
Read Blog Post
William Shatner Standing Next To The Hack The Galaxy Logo And A Space Ship...in Space!
Why William Shatner Is Sending Developers to Space and How to Join Them
Read Blog Post

Subscribe Via Email

Thank You!

You’ve Been Subscribed.