Create a Transaction

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. GrailPay 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 to GrailPay.

Bank-Link provides the ability to retrieve the latest balance from a bank account, which helps us validate the transaction amount through ACH. GrailPay also checks 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

Endpoint

/3p/api/v1/transaction

Request Payload

{
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "amount": 12000
}

{
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "amount": 12000,
    "source_bank_account": {
        "uuid": "9b3ef193-5d7e-417c-b8af-5add4a2aadfd",
        "aggregator_type": "bank_link"
    }
}

{
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
    "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
    "amount": 12000,
    "source_bank_account": {
        "uuid": "9b3ef193-5d7e-417c-b8af-5add4a2aadfd",
        "aggregator_type": "bank_link"
    },
    "destination_bank_account": {
        "uuid": "9b3dd151-f50f-42c3-a082-553bddd5fd6e",
        "aggregator_type": "bank_link"
    }
}

{
    "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
  	"processor_mid": "208202439880",
  	"amount": 12000,
  	"client_reference_id": ""
}

Fields	Type	Is Required	Description
payer_uuid	string	Yes	Identifier of entity sending funds.
payee_uuid	string		Identifier of entity receiving funds. Required if `processor_mid` is `null`
processor_mid	string		Required if `payee_uuid` is `null`
amount	int	Yes	Amount in cents only
client_reference_id	string		Client refeorObjectrence or order id
transaction_fee	int		Vendor fee in cents only
speed	string		Possible values: standard sameday
company_name	string:16		Company name field in the ACH transaction text. Debit: if not specified, defaults to the payee name. Credit: Will always appear as GrailPay
description	string:10		Description field in the ACH transaction text. Credit: if not specified, defaults to the payer name.
addenda	string:80		Addenda 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.uuid	string\|uuid		Payer bank account uuid
source_bank_account.aggregator_type	string		Possible values: plaid manual bank_link
destination_bank_account.uuid	string\|uuid		Payee bank account uuid
destination_bank_account.aggregator_type	string		Possible values: plaid manual bank_link
payout_delay_days_min	int
failure_simulation	string		Possible 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

Code	Message
401	Unauthorized
403	Forbidden
404	Not Found
422	Unprocessable Content

Transaction Statuses

Status	Description
CAPTURE_PENDING	ACH payment can be canceled while they remain in the CAPTURE_PENDING status.
CAPTURE_ACH_PENDING	The ACH payment is being processed and cannot be canceled at this time.
CAPTURE_ACH_FAILED	The ACH payment failed due to an error.
CANCELED	The ACH payment has been canceled.
PAYOUT_PENDING_ACH	The ACH payment have been processed successfully and is waiting to be initiated for payout to the payee.
IN_PAYOUT	The payout (crediting funds to the payee via ACH) has been initiated.
PAYOUT_ACH_PENDING	The payout is being processed.
PAYOUT_ACH_FAILED	The payout failed due to an error.
PAYOUT_COMPLETE	The payout have been processed successfully.
FINANCING	The ACH payment is currently being processed through the Financing widget.
CLAWBACK_PENDING	A new ACH will be created to return money from the payee to GrailPay when an ACH payment fails for any reason and the payout has already been processed.
CLAWBACK_ACH_PENDING	New ACH is being been processed.
CLAWBACK_COMPLETE	New ACH has been processed successfully.
CLAWBACK_ACH_FAILED	New ACH has been failed due to an error.

Capture Statuses

Status	Description
CAPTURE_PENDING	The ACH payment from the payer can be canceled as long as it remains in the CAPTURE_PENDING status.
CAPTURE_ACH_PENDING	The ACH payment from the payer is being processed and cannot be canceled at this time.
CAPTURE_ACH_FAILED	The ACH payment from the payer failed due to an error.
CAPTURE_COMPLETE	The ACH payment from the payer have been processed successfully.

Payout Statuses

Status	Description
PAYOUT_ACH_PENDING	The payout is being processed to the payee.
PAYOUT_ACH_FAILED	The payout failed due to an error.
PAYOUT_COMPLETE	The payout have been processed successfully.

Clawback Statuses

Status	Description
CLAWBACK_PENDING	A new ACH will be created to return money from the payee to GrailPay whenever an ACH payment fails and the payout has already been processed.
CLAWBACK_ACH_PENDING	The ACH from the payee to GrailPay is being processed.
CLAWBACK_ACH_FAILED	The ACH from the payee to GrailPay has failed due to an error.
CLAWBACK_COMPLETE	The ACH from the payee to GrailPay has been processed successfully.

Reverse Payout Statuses

Status	Description
REVERSE_PAYOUT_PENDING	A new entity has been created to return money from GrailPay to the payer when the payout fails for any reason and the ACH payment has already been processed.
REVERSE_PAYOUT_ACH_PENDING	The ACH from GrailPay to the payer is being processed.
REVERSE_PAYOUT_ACH_FAILED	The ACH from GrailPay to the payer has failed due to an error.
REVERSE_PAYOUT_COMPLETE	The ACH from GrailPay 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.