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 servers as the unique identifier for each transaction, to be used for get information and status of particular transaction. Please note that only one transaction can be created per request.

This request processes the transfer of money between two banks. 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 provide 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 across various domains:

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 value: plaid manual bank_link
destination_bank_account.uuid	string\|uuid		Payee bank account uuid
destination_bank_account.aggregator_type	string		Possible value: plaid manual bank_link
payout_delay_days_min	int

Response Object

Note: Amounts and fees are expressed in cents.

{
    "status": true,
    "message": "",
    "data": {
      "uuid": "b5c337d8-d886-11ed-afa1-0242ac120002",
      "payer_uuid": "aae3664b-db18-428c-9a2f-a876f259a7c3",
      "payee_uuid": "54f964d4-7ade-4cd1-a278-4f21cad18a2b",
      "transaction_status": "CAPTURE_ACH_PENDING",
      "amount": 12000,
      "transaction_fee": 300,
      "currency": "USD",
      "client_reference_id": "",
      "payout_delay_days": 0,
      "company_name": null,
      "description": null,
      "addenda": null,
      "type": "api",
      "created_at": "2023-04-11 14:25:26",
      "updated_at": "2023-04-11 16:25:26"
    },
    "errors": []
}

Errors & Warnings

Code	Message
401	Unauthorize Request
403
404
422

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 (Reverse Payout) 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 (Reverse Payout) is being been processed
CLAWBACK_COMPLETE	New ACH (Reverse Payout) has been processed successfully
CLAWBACK_ACH_FAILED	New ACH (Reverse Payout) has been failed due to an error.