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.
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.
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:
The following table outlines the possible inputs for CashPay:
|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.|
Please note that:
paymentMethods.cashtype requires client configuration. Contact the technical team to assist in enabling your client for this feature.
- For now,
cash.atmis the only cash type that can be enabled.
- Not setting the
paymentMethodsfield 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.enabledfield with a value of
- Due to the limitations of ATMs, the
amountthat can be received using the Cash at ATM payment method is limited to denominations of 10. This is later specified on the response as
CashAtmPaymentMethodDetails, and on transaction webhooks/queries as the
payerInformationobject 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 8061) 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
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.
To determine which payment method was used to complete the payment request we will look at the
payer field on the
PaymentInitiationBankAccountPayerfield inidicates that the payment was completed using a bank transfer.
PaymentInitiationCashAtmPayerfield 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
completedWithcan be either
- This mutation will mark a payment request as
COMPLETEDto simulate that funds have been received. If
paymentwebhooks 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.