Guarantees

Guarantees are part of GrailPay’s risk evaluation system. They build on the same underlying risk signals as Transaction Intelligence, but rather than returning a score for you to threshold yourself, they return a decision.

---

​

Accounts Receivable Guarantees

An accounts receivable guarantee applies to funds being collected by a business. The payee is a verified business entity—one whose organization details, tax identifier, and beneficial owners have been supplied and evaluated—and the payer is the party being debited to satisfy what that business is owed. The payer may be an individual or an organization. Because the payee is a known and verified business, the risk in a receivable sits almost entirely on the payer side. This is why the request asks for considerably more about the payer than their bank account alone. Alongside identity and location, you supply behavioral context: when the payer’s account was opened on your platform, how much they have spent, how many transactions they have completed, whether this is their first, and the device and channel they are transacting from. GrailPay holds none of this history—it exists only on your platform—and it is what distinguishes an established customer from one who appeared this morning. To request a guarantee, send a POST request with details about the payer, the payee, and the transaction. GrailPay evaluates both parties against its risk signals and returns:

• Guarantee ID – A UUID identifying the guarantee record created for this request. Retain this value; it is the identifier used to cancel the guarantee.
• Decision – Either guarantee or no_guarantee.

Transaction details describe the debit itself: the amount, the SEC code under which it will be originated, the date it was initiated, and the processing speed. For full request and response examples, see the Guarantee API reference.

​

Usage Recommendations

• Send amounts as integers in cents. A transaction at or above 1000000 cents ($10,000) is declined automatically and returns no_guarantee.
• Send exactly one of payer.individual or payer.organization. Name, email, and phone belong to whichever identity object you send rather than to the payer itself.
• Send all timestamps in UTC. The only date field that is not a timestamp is a beneficial owner’s dob, which is a calendar date.
• Use tax_id for every tax identifier—individual, organization, and beneficial owner alike.
• Populate the behavioral fields on the payer as completely and accurately as possible. These describe the payer’s history on your platform and are not available to GrailPay from any other source.
• Store the returned guarantee ID against your own record of the transaction so that a cancellation can be issued without a lookup.

---

​

Cancel Guarantees

Not every guarantee that gets issued ends up being wanted. Sometimes the transaction itself falls away—a customer abandons a checkout, an order is voided, a duplicate submission is caught downstream. Other times the transaction proceeds exactly as planned and you simply decide you do not need it guaranteed: the payer turns out to be a long-standing customer, the amount is small enough to absorb, or your own review clears it. Either way, the guarantee is no longer serving a purpose and should be released rather than left standing. A guarantee can be cancelled for 15 minutes, measured from the time the original request was received rather than from when your system read the response. Cancellation is performed against the guarantee ID returned at creation, not against a transaction or request identifier—which is why that value is worth persisting alongside your own record of the transaction at the moment you receive it. For full request and response examples, see the Cancel Guarantee API reference.

---

​

Sandbox Testing

The sandbox reserves a small set of routing numbers that return a fixed decision. Use them to build and test against each outcome so you can see how real results will behave, without depending on live decisioning to produce a particular answer. Sandbox base URL: https://risk-api-sandbox.grailpay.com

​

Selection Is Driven by the Payer

Scenarios are selected by payer.bank_account.routing_number alone. The payee’s routing number is not evaluated for this purpose, and account numbers are not reserved—any value that passes standard validation will do. Your request is validated in full before a scenario is selected. An invalid payload is rejected on its own terms, so a reserved routing number will not rescue a request that is missing required fields, sends both payer.individual and payer.organization, or violates any other rule.

​

Test Routing Numbers

​

What Each Routing Number Returns

For calls to POST /api/v3/guarantees/receivable, each reserved routing number returns the following: Both 200 scenarios create a real guarantee record, so the returned ID behaves exactly as it would in production—you can use 000000001 to test your cancellation flow end to end. The 503 scenario returns a message indicating that guarantee decisioning is experiencing a disruption and should be retried later; no guarantee is created, so there is nothing to cancel.

---

​

Questions?

If you’re encountering any issues, please reach out to [email protected].

---