Once authenticated, the client application can send a request to create a new transaction by providing relevant details such as the payment amount, sender and receiver. We will then return a UUID, which serves as the unique identifier and can be used to fetch the details and status of the transaction. Please note that only one transaction can be created per request. This request processes the transfer of money between two bank accounts. To complete the transaction, both the payer (the person sending the money) and the payee (the person receiving the money) must have active bank accounts that are connected within the application. Bank-Link provides the ability to retrieve the latest balance from a bank account, which helps us validate the transaction amount through ACH. We also check the latest balance and returns an error if the balance is lower than the transaction amount. We facilitate transactions between the following entities:
  • Business To Business
  • Business To Person
  • Person To Business

​
Failure Simulation

GrailPay allows you to simulate transaction failures when testing your integration in our sandbox environment. To do this, include the failure_simulation parameter in the payload when creating a transaction. This parameter accepts one of two string values, each triggering a failed transaction with an ACH Return Code of R01 (Insufficient Funds):
  • beforePayout – Simulates a failure before the payout (credit) is sent to the destination bank.
  • afterPayout – Simulates a failure after the payout (credit) has already been sent to the destination bank.
By using these failure scenarios, you can ensure your integration correctly handles ACH failures at different stages of the transaction lifecycle.

​
Testing

To test transactions in GrailPay’s Sandbox environment, you’ll need two bank accounts:
  • One for the entity making the payment
  • One for the entity receiving the payment
Since this is a test environment, you can simulate an active bank account by using a random 12-digit account number along with a specific routing number. Simply submit these details when using the Onboard a Person, Onboard a Business, or Add Bank Account APIs.

​
Endpoint

POST   /3p/api/v1/transaction  

​
Request Payload

{
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "amount": 12000
}
FieldsTypeIs RequiredDescription
payer_uuidstringYesIdentifier of entity sending funds.
payee_uuidstringIdentifier of entity receiving funds. Required if processor_mid is null
processor_midstringRequired if payee_uuid is null
amountintYesAmount in cents only
client_reference_idstringClient refeorObjectrence or order id
transaction_feeintVendor fee in cents only
speedstringPossible values:standard sameday
company_namestring:16Company name field in the ACH transaction text. Debit: if not specified, defaults to the payee name. Credit: Will always appear as GrailPay
descriptionstring:10Description field in the ACH transaction text. Credit: if not specified, defaults to the payer name.
addendastring:80Addenda field in the ACH transaction text. Only supported on CCD transactions. Debit: if payer is a person, will not appear. Credit: If payee is a person, will not appear.
source_bank_account.uuidstring|uuidPayer bank account uuid
source_bank_account.aggregator_typestringPossible values: plaid manual bank_link
destination_bank_account.uuidstring|uuidPayee bank account uuid
destination_bank_account.aggregator_typestringPossible values: plaid manual bank_link
payout_delay_days_minint
failure_simulationstringPossible values: BeforePayout AfterPayout

​
Response Object

Note: Amounts and fees are expressed in cents. 
{
    "status": true,
    "message": "",
    "data": {
        "uuid": "9d86dcad-87dd-4ebc-9356-25b34b352ea6",
        "payer_uuid": "9d7ec46a-93cf-4b01-bb09-a058fc8b7cc5",
        "payee_uuid": "9d7ec435-0b26-4c9f-8b5b-cb5cdf62ccde",
        "transaction_status": "CAPTURE_PENDING",
        "currency": "USD",
        "amount": 975,
        "transaction_fee": 0,
        "client_reference_id": null,
        "payout_delay_days": 0,
        "company_name": "John Clark",
        "description": null,
        "addenda": null,
        "type": "api",
        "speed": "sameday",
        "processor_mid": null,
        "capture_status": "CAPTURE_PENDING",
        "payout_status": null,
        "clawback_status": null,
        "reverse_payout_status": null,
        "failure_code": null,
        "failure_reason": null,
        "cancel_reason": null,
        "payer_bank_account": {
            "uuid": "9d7ecbf1-3827-469e-ab29-22b4a61f67fc",
            "aggregator_type": "manual"
        },
        "payee_bank_account": {
            "uuid": null,
            "aggregator_type": null
        },
        "created_at": "2024-11-19 14:12:15",
        "updated_at": "2024-11-19 14:12:16"
    },
    "errors": null,
    "error_code": null
}

​
Errors & Warnings

CodeMessage
401Unauthorized
403Forbidden
404Not Found
422Unprocessable Content

​
Transaction Statuses

StatusDescription
CAPTURE_PENDINGACH payment can be canceled while they remain in the CAPTURE_PENDING status.
CAPTURE_ACH_PENDINGThe ACH payment is being processed and cannot be canceled at this time.
CAPTURE_ACH_FAILEDThe ACH payment failed due to an error.
CANCELEDThe ACH payment has been canceled.
PAYOUT_PENDING_ACHThe ACH payment have been processed successfully and is waiting to be initiated for payout to the payee.
IN_PAYOUTThe payout (crediting funds to the payee via ACH) has been initiated.
PAYOUT_ACH_PENDINGThe payout is being processed.
PAYOUT_ACH_FAILEDThe payout failed due to an error.
PAYOUT_COMPLETEThe payout have been processed successfully.
FINANCINGThe ACH payment is currently being processed through the Financing widget.
CLAWBACK_PENDINGA new ACH will be created to return money from the payee to us when an ACH payment fails for any reason and the payout has already been processed.
CLAWBACK_ACH_PENDINGNew ACH is being been processed.
CLAWBACK_COMPLETENew ACH has been processed successfully.
CLAWBACK_ACH_FAILEDNew ACH has been failed due to an error.

​
Capture Statuses

StatusDescription
CAPTURE_PENDINGThe ACH payment from the payer can be canceled as long as it remains in the CAPTURE_PENDING status.
CAPTURE_ACH_PENDINGThe ACH payment from the payer is being processed and cannot be canceled at this time.
CAPTURE_ACH_FAILEDThe ACH payment from the payer failed due to an error.
CAPTURE_COMPLETEThe ACH payment from the payer have been processed successfully.

​
Payout Statuses

StatusDescription
PAYOUT_ACH_PENDINGThe payout is being processed to the payee.
PAYOUT_ACH_FAILEDThe payout failed due to an error.
PAYOUT_COMPLETEThe payout have been processed successfully.

​
Clawback Statuses

StatusDescription
CLAWBACK_PENDINGA new ACH will be created to return money from the payee to us whenever an ACH payment fails and the payout has already been processed.
CLAWBACK_ACH_PENDINGThe ACH from the payee to us is being processed.
CLAWBACK_ACH_FAILEDThe ACH from the payee to us has failed due to an error.
CLAWBACK_COMPLETEThe ACH from the payee to us has been processed successfully.

​
Reverse Payout Statuses

StatusDescription
REVERSE_PAYOUT_PENDINGA new entity has been created to return money from us to the payer when the payout fails for any reason and the ACH payment has already been processed.
REVERSE_PAYOUT_ACH_PENDINGThe ACH from us to the payer is being processed.
REVERSE_PAYOUT_ACH_FAILEDThe ACH from us to the payer has failed due to an error.
REVERSE_PAYOUT_COMPLETEThe ACH from us to the payer has been processed successfully.

​
Failure Simulation

** The failure_simulation field in the payload is only valid in the sandbox environment.

​
BeforePayout

  • The TransactionFailed event will be triggered 15 minutes after the creation of the transaction.
  • No payout will be processed.

​
AfterPayout

  • The TransactionFailed event will be triggered 30 mins after the creation of the transaction.
  • The PayoutCompleted event will be triggered.
  • The Clawback events will be triggered.