DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Escrow Payments

How to create escrow payments for your marketplace on Rave.

Suggest Edits

Rave allows you to collect escrow payments for your marketplaces, along with Spliting transactions to sellers on your platform. To do this we require you pass a metadata value via the Rave inline or API.

When you pass the required metadata the funds would be held in escrow and you would be able to release the funds from escrow by making an API call to our settlement endpoint /transactions/escrow/settle.

See how to set up a transaction for Escrow below.

📘

Setting a transaction in escrow

To set a transaction in escrow you would need to pass a metadata value as

meta: [{ metaname: "rave_escrow_tx", metavalue: 1}]

<form>
    <script src="https://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 2000,
            currency: "NGN",
            txref: "rave-123456",
            subaccounts: [
              {
                id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E" // This assumes you have setup your commission on the dashboard.
              }
            ],
            meta: [{
                metaname: "rave_escrow_tx",
                metavalue: 1
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

{
  "PBFPubKey": "FLWPUBK-4e581ebf8372cd691203b27227e2e3b8-X",
  "cardno": "5438898014560229",
  "cvv": "890",
  "expirymonth": "09",
  "expiryyear": "19",
  "currency": "NGN",
  "country": "NG",
  "amount": "10",
  "email": "[email protected]",
  "phonenumber": "0902620185",
  "firstname": "temi",
  "lastname": "desola",
  "IP": "355426087298442",
  "txRef": "MC-" + Date.now(),// your unique merchant reference
  "meta": [{metaname: "rave_escrow_tx", metavalue: 1}],
  "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
  "device_fingerprint": "69e6b7f0b72037aa8428b70fbe03986c"
}

When a transaction is done it is set in escrow and returns with a status from the Verify Payment call with a sample response that looks like this.

📘

Checking the status of the escrow

When you call the Verify Payment the meta object contains meta details of the escrow payment. When the meta value for rave_escrow_tx is set to 1 it means the payment is still in escrow. When the value is set to SETTLED it means the payment has been settled according to the merchant's settlement cycle.

{
    "status": "success",
    "message": "Tx Fetched",
    "data": {
        "txid": 348813,
        "txref": "rave-checkout-1544113667557",
        "flwref": "ACHG-1544113684236",
        "devicefingerprint": "532b4e9fa7695279392f4780b9868b9b",
        "cycle": "one-time",
        "amount": 1000,
        "currency": "NGN",
        "chargedamount": 1000,
        "appfee": 15,
        "merchantfee": 0,
        "merchantbearsfee": 1,
        "chargecode": "00",
        "chargemessage": "Pending OTP validation",
        "authmodel": "AUTH",
        "ip": "197.149.95.62",
        "narration": "Synergy Group",
        "status": "successful",
        "vbvcode": "N/A",
        "vbvmessage": "N/A",
        "authurl": "NO-URL",
        "acctcode": "00",
        "acctmessage": "Approved Or Completed Successfully",
        "paymenttype": "account",
        "paymentid": "2",
        "fraudstatus": "ok",
        "chargetype": "normal",
        "createdday": 4,
        "createddayname": "THURSDAY",
        "createdweek": 49,
        "createdmonth": 11,
        "createdmonthname": "DECEMBER",
        "createdquarter": 4,
        "createdyear": 2018,
        "createdyearisleap": false,
        "createddayispublicholiday": 0,
        "createdhour": 16,
        "createdminute": 28,
        "createdpmam": "pm",
        "created": "2018-12-06T16:28:03.000Z",
        "customerid": 63356,
        "custphone": "N/A",
        "custnetworkprovider": "UNKNOWN PROVIDER",
        "custname": "Anonymous customer",
        "custemail": "[email protected]",
        "custemailprovider": "GMAIL",
        "custcreated": "2018-11-19T12:11:02.000Z",
        "accountid": 134,
        "acctbusinessname": "Synergy Group",
        "acctcontactperson": "Desola Ade",
        "acctcountry": "US",
        "acctbearsfeeattransactiontime": 1,
        "acctparent": 1,
        "acctvpcmerchant": "N/A",
        "acctalias": "temi",
        "acctisliveapproved": 0,
        "orderref": "URF_1544113683398_6624935",
        "paymentplan": null,
        "paymentpage": null,
        "raveref": "RV31544113682885E470F9FD90",
        "amountsettledforthistransaction": 985,
        "account": {
            "id": 2,
            "account_number": "0690000031",
            "account_bank": "044",
            "first_name": "NO-NAME",
            "last_name": "NO-LNAME",
            "account_is_blacklisted": 0,
            "createdAt": "2016-12-31T04:09:24.000Z",
            "updatedAt": "2018-12-06T18:47:41.000Z",
            "deletedAt": null,
            "account_token": {
                "token": "flw-t0e1bb79f967612fc1-k3n-mock"
            }
        },
        "meta": [
            {
                "id": 1254036,
                "metaname": "rave_escrow_tx",
                "metavalue": "1",
                "createdAt": "2018-12-06T16:28:03.000Z",
                "updatedAt": "2018-12-06T16:48:32.000Z",
                "deletedAt": null,
                "getpaidTransactionId": 348813
            },
            {
                "id": 1254037,
                "metaname": "subaccount_split",
                "metavalue": "{\"subaccount\":\"RS_69CE4F58080913116F96E3CE730E7D23\"}",
                "createdAt": "2018-12-06T16:28:03.000Z",
                "updatedAt": "2018-12-06T16:28:03.000Z",
                "deletedAt": null,
                "getpaidTransactionId": 348813
            }
        ]
    }
}

{
    "status": "success",
    "message": "Tx Fetched",
    "data": {
        "txid": 348813,
        "txref": "rave-checkout-1544113667557",
        "flwref": "ACHG-1544113684236",
        "devicefingerprint": "532b4e9fa7695279392f4780b9868b9b",
        "cycle": "one-time",
        "amount": 1000,
        "currency": "NGN",
        "chargedamount": 1000,
        "appfee": 15,
        "merchantfee": 0,
        "merchantbearsfee": 1,
        "chargecode": "00",
        "chargemessage": "Pending OTP validation",
        "authmodel": "AUTH",
        "ip": "197.149.95.62",
        "narration": "Synergy Group",
        "status": "successful",
        "vbvcode": "N/A",
        "vbvmessage": "N/A",
        "authurl": "NO-URL",
        "acctcode": "00",
        "acctmessage": "Approved Or Completed Successfully",
        "paymenttype": "account",
        "paymentid": "2",
        "fraudstatus": "ok",
        "chargetype": "normal",
        "createdday": 4,
        "createddayname": "THURSDAY",
        "createdweek": 49,
        "createdmonth": 11,
        "createdmonthname": "DECEMBER",
        "createdquarter": 4,
        "createdyear": 2018,
        "createdyearisleap": false,
        "createddayispublicholiday": 0,
        "createdhour": 16,
        "createdminute": 28,
        "createdpmam": "pm",
        "created": "2018-12-06T16:28:03.000Z",
        "customerid": 63356,
        "custphone": "N/A",
        "custnetworkprovider": "UNKNOWN PROVIDER",
        "custname": "Anonymous customer",
        "custemail": "[email protected]",
        "custemailprovider": "GMAIL",
        "custcreated": "2018-11-19T12:11:02.000Z",
        "accountid": 134,
        "acctbusinessname": "Synergy Group",
        "acctcontactperson": "Desola Ade",
        "acctcountry": "US",
        "acctbearsfeeattransactiontime": 1,
        "acctparent": 1,
        "acctvpcmerchant": "N/A",
        "acctalias": "temi",
        "acctisliveapproved": 0,
        "orderref": "URF_1544113683398_6624935",
        "paymentplan": null,
        "paymentpage": null,
        "raveref": "RV31544113682885E470F9FD90",
        "amountsettledforthistransaction": 985,
        "account": {
            "id": 2,
            "account_number": "0690000031",
            "account_bank": "044",
            "first_name": "NO-NAME",
            "last_name": "NO-LNAME",
            "account_is_blacklisted": 0,
            "createdAt": "2016-12-31T04:09:24.000Z",
            "updatedAt": "2018-12-06T18:47:41.000Z",
            "deletedAt": null,
            "account_token": {
                "token": "flw-t0e1bb79f967612fc1-k3n-mock"
            }
        },
        "meta": [
            {
                "id": 1254036,
                "metaname": "rave_escrow_tx",
                "metavalue": "SETTLED",
                "createdAt": "2018-12-06T16:28:03.000Z",
                "updatedAt": "2018-12-06T16:48:32.000Z",
                "deletedAt": null,
                "getpaidTransactionId": 348813
            },
            {
                "id": 1254037,
                "metaname": "subaccount_split",
                "metavalue": "{\"subaccount\":\"RS_69CE4F58080913116F96E3CE730E7D23\"}",
                "createdAt": "2018-12-06T16:28:03.000Z",
                "updatedAt": "2018-12-06T16:28:03.000Z",
                "deletedAt": null,
                "getpaidTransactionId": 348813
            }
        ]
    }
}

Settling an Escrow payment

When the funds are in escrow and you would like to settle the seller for the funds you would need to call our settlement endpoint.

Endpoint: https://api.ravepay.co/v2/gpx/transactions/escrow/settle

Sample Request

{
	"id": "348813", // this is the txid value returned in the v2/verify response.
	"secret_key": "FLWSECK-*************************-X" // your merchant secret key.
}

Sample Response

{
    "status": "success",
    "message": "SUCCESS",
    "data": "Transaction settled"
}

Once you call this API, an automatic settlement is done to the provided bank account (for subaccounts the funds go into the bank account you set up while creating the subaccount profile). Once the settlement is completed the value for rave_escrow_tx found in the meta object of the Verify Payment response changes to SETTLED.

Refunding an Escrow payment

You can return the payment back to a customer should in case they raised a dispute or wanted a full refund of the items they bought.

To refund an escrow payment, you would need to call the refund API below.

Endpoint: https://api.ravepay.co/v2/gpx/transactions/escrow/refund

Sample Request

{
    "id": "348813", // this is the txid value returned in the v2/verify response.
    "comment":"Freelancer did not deliver",
    "secret_key": "FLWSECK-**********************-X" // This is your merchant secret key.
}

Sample Response

{
    "status": "success",
    "message": "SUCCESS",
    "data": "Transaction refunded"
}

Once the refund is initiated your balance would be depleted for the refund amount equivalent.

Partial Escrow Refund

To perform a partial escrow refund, you would be required to add the refund amount in your initial refund payload. Here's a sample partial escrow refund payload:

{
    "id": "1380151",
    "amount": "500",
    "comment":"Freelancer did not deliver",
    "secret_key": "FLWSECK-*************-X"
}

Sample Response:

{
    "status": "success",
    "message": "SUCCESS",
    "data": "Transaction refunded"
}

Updated over 4 years ago