Cancel an Escrow
Tags: rapydpayments, escrow, api, paymentacceptance
Published: 2024-01-05 17:22:44

_**By Kyle Pollock**_

Today, the housing marketing is uncertain for certain buyers and sellers not knowing if the market will change. Will mortgage rates go up further, or will the come down? During a sale of any house, all parties should be prepared for any outcome, including the agent, broker, realtor, and facilitator. 

Having a third party escrow account is essential to ensure funds are secured, and carefully held until the full completion of the sale. In an case where the sale falls through, canceling the escrow can be a tool to use when a buyer or seller backs out. 

You can create a payment in EUR (Euros) using [SEPA Direct Debit](https://docs.rapyd.net/en/sepa-direct-debit.html#idm46086356174800). Follow the escrow payment below. After the payment is made into the escrow account, and before manually releasing the escrow you can cancel it. This will essential be a refund to the home buyer. 

## Create Payment with Escrow

### Request
```
POST https://sandboxapi.rapyd.net/v1/payments 
```


``` 
{
	"amount": 200000,
	"currency": "EUR",
	"complete_payment_url": "https://rapyd.net",
	"error_payment_url": "https://docs.rapyd.net",
    "customer":"cus_1930a7dab2a80a7896cbcf98c2e2c762",
	"description": "Payment by bank redirect",
       "escrow": true,
	"payment_method": {
		"type": "gb_sepadirectdebit_bank",
		"fields": {
            
        }
	},
	"capture": null,
	"ewallets": [
		{
			"ewallet": "ewallet_fbcc006de0394bc2b24308eddca45c64",
			"percentage": 100
		}
	],
	"metadata": {
		"merchant_defined": true
             

	}
}
```

### Response 
```
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "eeece751-4ad0-44f7-b226-9ba4bca944a9"
    },
    "data": {
        "id": "payment_f3145cebe0381294e9b5412a3bb8378a",
        "amount": 0,
        "original_amount": 200000,
        "is_partial": false,
        "currency_code": "EUR",
        "country_code": "GB",
        "status": "ACT",
        "description": "Payment by bank redirect",
        "merchant_reference_id": "",
        "customer_token": "cus_1930a7dab2a80a7896cbcf98c2e2c762",
        "payment_method": "other_1b16b1e5b561269d2d0afeae4ada5541",
        "payment_method_data": {
            "id": "other_1b16b1e5b561269d2d0afeae4ada5541",
            "type": "gb_sepadirectdebit_bank",
            "category": "bank_redirect",
            "metadata": {},
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "user_authentication",
            "bic_swift": "",
            "account_last4": "",
            "redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-redirect?token=other_1b16b1e5b561269d2d0afeae4ada5541&complete_payment_url=undefined&error_payment_url=undefined"
        },
        "auth_code": null,
        "expiration": 1697490886,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_f3145cebe0381294e9b5412a3bb8378a&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": 1696281286,
        "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": "You will be redirected to a website to authorize the transaction."
                    },
                    {
                        "step2": "Enter your IBAN account number."
                    },
                    {
                        "step3": "Enter the one-time password (OTP) that you receive."
                    },
                    {
                        "step4": "You will be notified that the payment succeeded."
                    }
                ]
            }
        ],
        "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
        "ewallets": [
            {
                "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
                "amount": 200000,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "gb_sepadirectdebit_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_a9bb2236132c93b73f10e577a3fa281c",
            "payment": "payment_f3145cebe0381294e9b5412a3bb8378a",
            "currency": "EUR",
            "amount_on_hold": 0,
            "total_amount_released": 0,
            "status": "pending",
            "escrow_release_days": null,
            "created_at": 1696281286,
            "updated_at": 1696281286,
            "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
    }
}
```

Before completing the 

Now the payment should be closed, but the escrow still on hold. 

## Retrieve Escrow

### Request 

```
GET https://sandboxapi.rapyd.net/v1/payments/:payment/escrows/:escrow

# Path Variables 
# payment: payment_f3145cebe0381294e9b5412a3bb8378a
# escrow: escrow_a9bb2236132c93b73f10e577a3fa281c
```

### Response 

```
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "85260e89-d74d-4bd0-9591-2bdf435ecf1c"
    },
    "data": {
        "id": "escrow_a9bb2236132c93b73f10e577a3fa281c",
        "payment": "payment_f3145cebe0381294e9b5412a3bb8378a",
        "currency": "EUR",
        "amount_on_hold": 0,
        "total_amount_released": 0,
        "status": "pending",
        "escrow_release_days": null,
        "escrow_releases": null,
        "created_at": 1696281286,
        "updated_at": 1696281286,
        "last_payment_completion": null
    }
}
```

You can now cancel the escrow. 

## Cancel Escrow 

### Request (Update Payment)

``` 
POST https://sandboxapi.rapyd.net/v1/payments/:payment 

# Path Variables
# Payment: payment_f3145cebe0381294e9b5412a3bb8378a
```
### Request Body
```
{
    "escrow":false
}
```

### Reponse

```
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "851d6692-ddeb-4601-9adb-defaefad6c92"
    },
    "data": {
        "id": "payment_f3145cebe0381294e9b5412a3bb8378a",
        "amount": 0,
        "original_amount": 200000,
        "is_partial": false,
        "currency_code": "EUR",
        "country_code": "GB",
        "status": "ACT",
        "description": "Payment by bank redirect",
        "merchant_reference_id": "",
        "customer_token": "cus_1930a7dab2a80a7896cbcf98c2e2c762",
        "payment_method": "other_1b16b1e5b561269d2d0afeae4ada5541",
        "payment_method_data": {
            "id": "other_1b16b1e5b561269d2d0afeae4ada5541",
            "type": "gb_sepadirectdebit_bank",
            "category": "bank_redirect",
            "metadata": {},
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "user_authentication",
            "bic_swift": "",
            "account_last4": ""
        },
        "auth_code": null,
        "expiration": 1697490886,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "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": 1696281286,
        "metadata": {},
        "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": "You will be redirected to a website to authorize the transaction."
                    },
                    {
                        "step2": "Enter your IBAN account number."
                    },
                    {
                        "step3": "Enter the one-time password (OTP) that you receive."
                    },
                    {
                        "step4": "You will be notified that the payment succeeded."
                    }
                ]
            }
        ],
        "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
        "ewallets": [
            {
                "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
                "amount": 200000,
                "percent": 100,
                "released_amount": 0,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "gb_sepadirectdebit_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_a9bb2236132c93b73f10e577a3fa281c",
            "payment": "payment_f3145cebe0381294e9b5412a3bb8378a",
            "currency": "EUR",
            "amount_on_hold": 0,
            "total_amount_released": 0,
            "status": "canceled",
            "escrow_release_days": null,
            "created_at": 1696281286,
            "updated_at": 1696281560,
            "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
    }
}
```

## Retrieve Escrow
### Request

Same request as above. 
```
GET https://sandboxapi.rapyd.net/v1/payments/:payment/escrows/:escrow

# Path Variables 
# payment: payment_f3145cebe0381294e9b5412a3bb8378a
# escrow: escrow_a9bb2236132c93b73f10e577a3fa281c
```

### Response 

```
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "85260e89-d74d-4bd0-9591-2bdf435ecf1c"
    },
    "data": {
        "id": "escrow_a9bb2236132c93b73f10e577a3fa281c",
        "payment": "payment_f3145cebe0381294e9b5412a3bb8378a",
        "currency": "EUR",
        "amount_on_hold": 0,
        "total_amount_released": 0,
        "status": "canceled",
        "escrow_release_days": null,
        "escrow_releases": null,
        "created_at": 1696281286,
        "updated_at": 1696281560,
        "last_payment_completion": null
    }
}
```
We now see the escrow status is canceled. We can now cancel the payment. 

## Cancel Payment

### Request
```
DELETE https://sandboxapi.rapyd.net/v1/payments/:payment

# Path Variables
# payment: payment_f3145cebe0381294e9b5412a3bb8378a
```

### Response 

```
{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a3f6c4ea-c644-428b-b274-2ff11b318d23"
    },
    "data": {
        "id": "payment_f3145cebe0381294e9b5412a3bb8378a",
        "amount": 0,
        "original_amount": 200000,
        "is_partial": false,
        "currency_code": "EUR",
        "country_code": "GB",
        "status": "CAN",
        "description": "Payment by bank redirect",
        "merchant_reference_id": "",
        "customer_token": "cus_1930a7dab2a80a7896cbcf98c2e2c762",
        "payment_method": "other_1b16b1e5b561269d2d0afeae4ada5541",
        "payment_method_data": {},
        "auth_code": null,
        "expiration": 1697490886,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "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": 1696281286,
        "metadata": {},
        "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": "You will be redirected to a website to authorize the transaction."
                    },
                    {
                        "step2": "Enter your IBAN account number."
                    },
                    {
                        "step3": "Enter the one-time password (OTP) that you receive."
                    },
                    {
                        "step4": "You will be notified that the payment succeeded."
                    }
                ]
            }
        ],
        "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
        "ewallets": [
            {
                "ewallet_id": "ewallet_fbcc006de0394bc2b24308eddca45c64",
                "amount": 200000,
                "percent": 100,
                "released_amount": 0,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {},
        "payment_method_type": "gb_sepadirectdebit_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_a9bb2236132c93b73f10e577a3fa281c",
            "payment": "payment_f3145cebe0381294e9b5412a3bb8378a",
            "currency": "EUR",
            "amount_on_hold": 0,
            "total_amount_released": 0,
            "status": "canceled",
            "escrow_release_days": null,
            "created_at": 1696281286,
            "updated_at": 1696281560,
            "last_payment_completion": null
        },
        "group_payment": "",
        "cancel_reason": null,
        "initiation_type": "customer_present",
        "mid": "",
        "next_action": "not_applicable",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": true
    }
}
```
The payment is now canceled and refunded to the customer that has backed out of the purchase.