> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grailpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guarantees

<Note>
  Guarantees are not enabled by default and require an approved account. If you would like to offer this
  functionality, contact your GrailPay integration support contact to have it enabled on your account.
</Note>

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](https://risk-api.grailpay.com/spec/#/Guarantee/684a26497ba87a4fd8a162121d596637).

### 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](https://risk-api.grailpay.com/spec/#/Guarantee/74349eb29e34d3e857b0253973702bfa).

***

## 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

| Payer Routing Number | Scenario                              | HTTP Status |
| -------------------- | ------------------------------------- | ----------- |
| `000000001`          | Approved                              | `200`       |
| `000000002`          | Declined                              | `200`       |
| `999999999`          | Decisioning temporarily unavailable   | `503`       |
| Any other value      | Falls through to live sandbox scoring | live        |

### What Each Routing Number Returns

For calls to `POST /api/v3/guarantees/receivable`, each reserved routing number returns the following:

| Payer Routing Number | `decision`     | Guarantee created |
| -------------------- | -------------- | ----------------- |
| `000000001`          | `guarantee`    | Yes               |
| `000000002`          | `no_guarantee` | Yes               |
| `999999999`          | none returned  | No                |

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.

<Note>
  These routing numbers are reserved in the sandbox only. In production they are treated as ordinary routing numbers
  and are scored live.
</Note>

***

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

***