CashPay Integration ProcessEarly Access

caution

This chapter includes information about features or aspects of the platform that are deemed Early Access.

Early Access features have added stability and will not encounter breaking changes, offering a backward compatible API Schema.

Certain Early Access features may not be accessible to all Stitch users by default. These features can be enabled on a per-client basis on request.

Postman Collection

CashPay requests can be created and tested using the Postman collection available here. These can be used by specifying your client credentials and supplying the custom request variables where required.

Generate Payment Request URL

Much like Pay By Bank, CashPay creation is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_paymentrequest scope. To create a payment initiation request, you'll need to ensure that the feature is enabled on your client.

To create the request, a GraphQL mutation is used to specify the requested amount, the references that will appear on the user and beneficiary's accounts, and the beneficiary details themselves.

Additional PaymentMethods

For now CashPay is only available as an additional payment method to bank transfer on Pay By Bank. Payment Requests that are created with the CashPay payment method will allow customers to choose cash in addition to bank transfer. Currently, we do not support CashPay without Pay By Bank.

An example of a GraphQL request to create a payment initiation request with the CashPay payment method is shown below:

Open in IDE ↗

The following table outlines the possible inputs for CashPay:

Status	Description
enabled	Boolean field used to specify enable or disable CashPay. Note that by default, this will be enabled.
mobileNumber	The mobile number of the user, used for OTP verification. This field must be specified per request.
reference	A customer reference field that the user specify when making their payment. If this is not provided, we will generate our own and return this on the response.

Cash Payment Method Details

Please note that:

• The paymentMethods.cash type requires client configuration. Contact the technical team to assist in enabling your client for this feature.
• For now, cash.atm is the only cash type that can be enabled.
• Not setting the paymentMethods field results in an Pay By Bank request. This will still include the cash payment method as set up on your client profile. To explicitly omit cash as a payment method, provide the paymentMethods.cash.enabled field with a value of false.
• Due to the limitations of ATMs, the amount that can be received using the Cash at ATM payment method is limited to denominations of 10. This is later specified on the response as amountRounded on CashAtmPaymentMethodDetails, and on transaction webhooks/queries as the amountReceived field on PaymentInitiationCashAtmPayer.
• The payerInformation object is required to be populated, as this facilitates with handling risk and fraud measures around this payment method. More information on these particular fields can be found here.

Expiring payment requests

It is highly recommended that an expireAt Date (ISO 8601) is supplied in the creation of any payment initiation request. At the specified date and time, the payment request status will automatically move to PaymentInitiationRequestExpired, if the payment is not yet successfully completed.

Subscribe to Webhooks

Since CashPay is a part of Pay By Bank, we subscribe to webhooks and receive payment updates in the same way.

If the subscription is successfully created, the body returned by the request will look like the sample in the Example Response tab in widget above.

For more information on receiving webhook events, listing active webhook subscriptions, unsubscribing from webhooks and validating signed webhook subscriptions, please visit the Webhooks page.

Retrieving CashPay Status

The status of a CashPay request works much like Pay By Bank.

To determine if and how a payment request was completed, we will need to retrieve its status.

Open in IDE ↗

Which payment method did the customer choose?

To determine which payment method was used to complete the payment request we will look at the payer field on the PaymentInitiationRequestCompleted state.

• The PaymentInitiationBankAccountPayer field inidicates that the payment was completed using a bank transfer.
• The PaymentInitiationCashTillPayer or PaymentInitiationCashAtmPayer field indicates that the payment was completed with cash at a Till or ATM respectively.

Testing CashPay Initiation

To test this process on your browser and run all the GraphQL examples in this guide prior to integrating with Stitch, you can use our sandbox. Learn more about the sandbox here.

For more information on CashPay, you can read our product release notes on the Stitch blog here.

Simulating Completed Payment Requests

We can simulate a user completing a payment request with cash using the following mutation.

• We specify the payment request we want to complete with an ID and choose the method we want to complete it with.
• In relation to cash products, the field completedWith can be either cash_atm or cash_retailer
• This mutation will mark a payment request as COMPLETED to simulate that funds have been received. If payment webhooks are subscribed to, a webhook will also be sent for this status update.

Please note that you must first create a payment request and that it can only be completed once.

Open in IDE ↗