Cash Payments

Increase revenue by integrating a better cash collection system

Rapyd's global cash-based over-the-counter network opens the world’s most popular payment method.

How It Works

Find Available Payment Methods

Note: For illustration purposes, we will use PE (Peru) and PEN (Peruvian Peso) for country and currency in the sample codes below.

Decide the payment methods you will accept so your customer can specify their payment methods on your payment page. To do that, use List Payment Methods by Country with the following parameters:

Query Parameter

Description

country

Enter PE as the country code.

currency

Enter PEN as the currency code.

List Payment Methods by Country request

Request a list of all available payment methods (PEN in this case).

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=PE&currency=PEN

// Message body absent
using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string country = "PE";
                string currency = "PEN";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/country?country={country}&currency={currency}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/country?country=PE&currency=PEN');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/country?country=PE&currency=PEN');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
from pprint import pprint

from utilities import make_request

country = 'PE'
currency = 'PEN'
results = make_request(method='get',
                       path=f'/v1/payment_methods/country?country={country}&currency={currency}')
pprint(results)

List Payment Methods by Country response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.**

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "a575ab97-c6ec-47f9-856d-0295f73ac6c2"
   },
   "data": [
{
           "type": "pe_cajaarequipa_cash",
           "name": "Caja Arequipa Peru/Cash Payments",
           "category": "cash",
           "image": "https://iconslib.rapyd.net/checkout/pe_cajaarequipa_cash.png",
           "country": "pe",
           "payment_flow_type": "cash",
           "currencies": [
               "PEN”
           ],
           "status": 1,
           "is_cancelable": false,
           "payment_options": [
               {
                   "name": "customer",
                   "type": "customer",
                   "regex": "",
                   "description": "make sure a customer was created with first_name, last_name and email",
                   "is_required": true,
                   "is_updatable": false
               },
               {
                   "name": "description",
                   "type": "string",
                   "regex": "",
                   "description": "the description field must be filled in.",
                   "is_required": true,
                   "is_updatable": false
               },
               {
                   "name": "expiration",
                   "type": "string",
                   "regex": "^[0-9]{10}$",
                   "is_required": true
               }
           ],
           "is_expirable": false,
           "is_online": false,
           "minimum_expiration_seconds": null,
           "maximum_expiration_seconds": null
       }
]
}

The response shows that pe_cajaarequipa_cash is an acceptable payment method in this case.

Note that a real response usually lists many payment methods.

Find Required Fields for the Payment Method

Identify the fields that your customer needs to complete for the payment method. To do that, use Get Payment Method Required Fields with the following parameter:

Path Parameter

Description

type

Enter pe_cajaarequipa_cash as the payment method type.

Get Payment Method Required Fields request

Request the set of required fields for a cash payment (Caja Arequipa Peru/Cash Payment in this case).

// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/pe_cajaarequipa_cash

// Message body absent
using System;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string type = "pe_cajaarequipa_cash";

                string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payment_methods/required_fields/{type}");

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const result = await makeRequest('GET', '/v1/payment_methods/required_fields/pe_cajaarequipa_cash');

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

try {
    $object = make_request('get', '/v1/payment_methods/required_fields/pe_cajaarequipa_cash');
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
from pprint import pprint

from utilities import make_request

payment_method = 'pe_cajaarequipa_cash'
results = make_request(method='get',
                       path=f'/v1/payment_methods/required_fields/{payment_method}')
pprint(results)

Get Payment Method Required Fields response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "b7ea9de2-28b7-49a1-8b6c-dac900b257b7"
   },
   "data": {
       "type": "pe_cajaarequipa_cash",
       "fields": [
           {
               "name": "userubigeo",
               "type": "string",
               "regex": "",
               "is_required": false,
               "instructions": "6 digits which identify State, Province and District"
           }
       ],
       "payment_method_options": [],
       "payment_options": [
           {
               "name": "customer",
               "type": "customer",
               "regex": "",
               "description": "make sure a customer was created with first_name, last_name and email",
               "is_required": true,
               "is_updatable": false
           },
           {
               "name": "description",
               "type": "string",
               "regex": "",
               "description": "the description field must be filled in.",
               "is_required": true,
               "is_updatable": false
           },
           {
               "name": "expiration",
               "type": "string",
               "regex": "^[0-9]{10}$",
               "is_required": true
           }
       ],
       "minimum_expiration_seconds": null,
       "maximum_expiration_seconds": null
   }
}

Process the Cash Payment

When your customer checks out on your website, use Create Payment with the following parameters to get Rapyd to process your customer's bank payment:

Body Parameter

Description

payment_method

Enter an object with the following field:
type - pe_cajaarequipa_cash

amount

Enter 100 as the payment amount.

currency

Enter PEN as the currency code.

Create Payment request

Request Rapyd to process your customer's payment (PEN 100 in this case) as a cash transaction.

// Request URL: POST https://sandboxapi.rapyd.net/v1/payments

// Message body:
{
   "amount": 100,
   "currency": "PEN",
   "payment_method": {
       "type": "pe_cajaarequipa_cash",
       "fields": {
       }
   }   
}
using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    amount = 100.00,
                    currency = "PEN",
                    payment_method = new
                    {
                        type = "pe_cajaarequipa_cash"
                    },
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}
const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      amount: 100.00,
      currency: 'PEN',
      payment_method: {
        type: 'pe_cajaarequipa_cash'
      }
    };
    const result = await makeRequest('POST', '/v1/payments', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}
<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

$body = [
    "amount" => "100.00",
    "currency" => "PEN",
    "payment_method" => [
        "type" => "pe_cajaarequipa_cash"
    ]
];

try {
    $object = make_request('post', '/v1/payments', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>
from pprint import pprint

from utilities import make_request

payment_body = {
    "amount": 100.00,
    "currency": "PEN",
    "payment_method": {
        "type": "pe_cajaarequipa_cash"
    }
}

results = make_request(method='post',
                       path='/v1/payments',
                       body=payment_body)
pprint(results)

Create Payment response

The response is generated below:

Note: See Payment Object for a description of the fields in the response.

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "b046cb5a-0a90-44de-99b8-0ccdedb6ba73"
   },
   "data": {
       "id": "payment_ad5b69484bf8863c5e14df82ca4895d5",
       "amount": 0,
       "original_amount": 100,
       "is_partial": false,
       "currency_code": "PEN",
       "country_code": "pe",
       "status": "ACT",
       "description": "test",
       "merchant_reference_id": "",
       "customer_token": "cus_7c4d7860c6b2db1a40da55920f33cf7c",
       "payment_method": "other_0eefd99416330f37687ed153b8c72db2",
       "expiration": 0,
       "captured": true,
       "refunded": false,
       "refunded_amount": 0,
       "receipt_email": "",
       "redirect_url": "",
       "complete_payment_url": "",
       "error_payment_url": "",
       "receipt_number": "",
       "flow_type": "",
       "address": null,
       "statement_descriptor": "Rapyd",
       "transaction_id": "",
       "created_at": 1600963416,
       "metadata": {},
       "failure_code": "",
       "failure_message": "",
       "paid": false,
       "paid_at": 0,
       "dispute": null,
       "refunds": null,
       "order": null,
       "outcome": null,
       "visual_codes": {},
       "textual_codes": {
           "TransactionID": "229845"
       },
       "instructions": [],
       "ewallet_id": "ewallet_be4ba8f13da40caa59a7e03022a8acfe",
       "ewallets": [
           {
               "ewallet_id": "ewallet_be4ba8f13da40caa59a7e03022a8acfe",
               "amount": 100,
               "percent": 100,
               "refunded_amount": 0
           }
       ],
       "payment_method_options": {},
       "payment_method_type": "pe_cajaarequipa_cash",
       "payment_method_type_category": "cash",
       "fx_rate": "",
       "merchant_requested_currency": null,
       "merchant_requested_amount": null,
       "fixed_side": "",
       "payment_fees": null,
       "invoice": "",
       "escrow": null,
       "group_payment": "",
       "initiation_type": "customer_present"
   }
}

The data section of this response shows:

  • The payment id is payment_ad5b69484bf8863c5e14df82ca4895d5.
    When you run this example in your own sandbox, you will get a different ID, which you will need for a later step.
  • The original_amount is 100.00.
  • The currency_code is PEN.
  • The status is ACT (active). This means that the payment process is active but not complete. Payment Object lists possible values for status.
  • The code for the one-time payment reference is 229845.
    In this example, the payment code is a number in string format. Payment codes also can be bar codes or QR codes.
  • Instructions for your customer to complete the payment.

Your website displays to your customer:

  • the amount to pay
  • the payment reference number
  • the instructions for completing the payment.

Close the Transaction

👍

Simulating a Cash Payment

The sandbox does not directly simulate the action of the customer depositing cash at a point-of-sale location. You can simulate this action with the procedure described in Complete Payment. For this, you will need the payment ID that you generated in your sandbox.

Configure your system to receive webhooks with the procedure described in Defining a Webhook Endpoint.

After your customer successfully makes a payment:

  1. The point-of-sale location informs Rapyd that the payment was completed successfully.
  2. Rapyd sends you a webhook with the details of the completed transaction. See Webhook - Payment Completed.

The webhook contains the same types of information as the response to the Create Payment request, except that the status (under data) now is CLO (closed). This shows that the transaction is complete.

At this point, you can display a (success) status on the screen to let your customer know that their purchase was successful and that they can go ahead and collect their purchased item/s.

📘

Looking for more in-depth technical information?

Want to see the Rapyd API methods and objects that you'll use?
Visit the Rapyd API Reference Documentation for more technical details.


Updated 5 days ago


What's Next

eWallets

Cash Payments


Increase revenue by integrating a better cash collection system

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.