Manual EFT Integration Process
Postman Collection
Manual EFT 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, Manual EFT 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, Manual EFT is only available as an additional payment method to bank transfer on Pay By Bank. Payment Requests that are created with the Manual EFT payment method will allow customers to choose Manual EFT in addition to bank transfer. Currently, we do not support Manual EFT without Pay By Bank.
An example of a GraphQL request to create a payment initiation request with the Manual EFT payment method is shown below:
The following table outlines the possible inputs for Manual EFT:
Status | Description |
---|---|
enabled | Boolean field used to specify enable or disable Manual EFT. Note that by default, this will be enabled. |
mobileNumber | The mobile number of the user, used for OTP verification. Either this or the email field must be specified per request. |
The email address of the user, used for OTP verification. Either this or the mobileNumber field must be specified per request. |
Please note that:
- The
paymentMethods.eft.manual
field requires client configuration. Contact the technical team to assist in enabling your client for this feature. - The
email
andmobileNumber
fields are used to verify users and reduce the risk of third-party deposits. - 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. - Not setting the
paymentMethods
field results in a Pay By Bank payment request. To explicitly omit Pay By Bank as a payment method, provide thepaymentMethods.eft.enabled
field with a value offalse
, as shown below:
variables: {
"amount": {
"quantity": 1,
"currency": "ZAR"
},
"payerReference": "KombuchaFizz",
"beneficiaryReference": "Joe-Fizz-01",
"externalReference": "example-e32e5478-325b-4869-a53e-2021727d2afe",
"beneficiaryName": "FizzBuzz Co.",
"beneficiaryBankId": "fnb",
"beneficiaryAccountNumber": "123456789",
"paymentMethods": {
"eft": {
"enabled": false,
"manual": {
"enabled": true,
"mobileNumber": "0812345678"
}
}
}
}
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.
Retrieving Manual EFT payments
Manual EFT deposits can be queried via the Client
node on the Stitch API. Please see Pagination
for more information about the query parameters.
We currently support two types of payment channels for EFT - Pay By Bank and Manual EFT deposits.
Note that this request needs a client token with the client_paymentrequest
scope.
This mutation returns the reference the unique user reference for the Manual EFT deposit. You can then use this reference as a filter to query for a particular Manual EFT deposit.
Subscribing to Manual EFT Webhooks
As Manual EFT is a part of Pay By Bank, we subscribe to webhooks and receive updates in the same way.
Visit the Webhooks page for information on receiving webhook events, unsubscribing from webhooks and validating subscriptions.
Retrieving Manual EFT Status
The status of a Manual EFT request works much like Pay By Bank
To determine 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 PaymentInitiationRequestCompleted
state.
- The
PaymentInitiationEftManualPayer
type indicates that the payment was completed using Manual EFT.
Settlement of Manual EFT payments
Manual EFT deposits are automatically settled in the same way that Pay By Bank pay-ins are settled. Please see Settlements for more details about how these payouts are processed.
Settlement Account Details
To view the settlement account configured on a client for Manual EFT, the below query can be run:
Testing Manual EFT 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 Manual EFT, 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 Manual EFT 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 Manual EFT, the field
completedWith
should beeft_manual
- This mutation will mark a payment request as
COMPLETED
to simulate that funds have been received. Ifpayment
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.