Incoming payment webhook and approval mechanism

Authorizations

X-Grid-Signature

string

header

required

Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid.

To verify the signature:

Get the Grid public key provided to you during integration
Decode the base64 signature from the header
Create a SHA-256 hash of the request body
Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

Body

application/json

timestamp

string<date-time>

required

ISO8601 timestamp when the webhook was sent (can be used to prevent replay attacks)

Example:

"2025-08-15T14:32:00Z"

webhookId

string

required

Unique identifier for this webhook delivery (can be used for idempotency)

Example:

"Webhook:019542f5-b3e7-1d02-0000-000000000007"

type

enum<string>

required

Type of webhook event Type of webhook event

Available options:

INCOMING_PAYMENT,

OUTGOING_PAYMENT,

TEST,

BULK_UPLOAD,

INVITATION_CLAIMED,

KYC_STATUS,

ACCOUNT_STATUS

Example:

"INCOMING_PAYMENT"

transaction

object

required

Show child attributes

transaction.id

string

required

Unique identifier for the transaction

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000004"

transaction.status

enum<string>

required

Status of a payment transaction

Available options:

CREATED,

PENDING,

PROCESSING,

COMPLETED,

REJECTED,

FAILED,

REFUNDED,

EXPIRED

transaction.type

enum<string>

required

Type of transaction (incoming payment or outgoing payment)

Available options:

INCOMING,

OUTGOING

transaction.source

Account Source · object

required

Source account details

Account Source
UMA Address Source

Show child attributes

transaction.source.accountId

string

required

Source account identifier

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

transaction.source.currency

string

required

Currency code for the source account

Example:

"USD"

transaction.destination

Account Destination · object

required

Destination account details

Account Destination
UMA Address Destination

Show child attributes

transaction.destination.accountId

string

required

Destination account identifier

Example:

"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

transaction.destination.currency

string

required

Currency code for the destination account

Example:

"EUR"

transaction.customerId

string

required

System ID of the customer (sender for outgoing, recipient for incoming)

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

transaction.platformCustomerId

string

required

Platform-specific ID of the customer (sender for outgoing, recipient for incoming)

Example:

"18d3e5f7b4a9c2"

transaction.receivedAmount

object

required

Amount received in the recipient's currency

Show child attributes

transaction.receivedAmount.amount

integer<int64>

required

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example:

12550

transaction.receivedAmount.currency

object

required

Show child attributes

transaction.receivedAmount.currency.code

string

Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)

Example:

"USD"

transaction.receivedAmount.currency.name

string

Full name of the currency

Example:

"United States Dollar"

transaction.receivedAmount.currency.symbol

string

Symbol of the currency

Example:

"$"

transaction.receivedAmount.currency.decimals

integer

Number of decimal places for the currency

Required range: x >= 0

Example:

2

transaction.settledAt

string<date-time>

When the payment was or will be settled

Example:

"2025-08-15T14:30:00Z"

transaction.createdAt

string<date-time>

When the transaction was created

Example:

"2025-08-15T14:25:18Z"

transaction.updatedAt

string<date-time>

When the transaction was last updated

Example:

"2025-08-15T14:30:00Z"

transaction.description

string

Optional memo or description for the payment

Example:

"Payment for invoice #1234"

transaction.counterpartyInformation

object

Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.

Example:

{
  "FULL_NAME": "John Sender",
  "BIRTH_DATE": "1985-06-15",
  "NATIONALITY": "DE"
}

transaction.reconciliationInstructions

object

Included for all transactions except those with "CREATED" status

Show child attributes

transaction.reconciliationInstructions.reference

string

required

Unique reference code that must be included with the payment to match it with the correct incoming transaction

Example:

"UMA-Q12345-REF"

transaction.rateDetails

object

Details about the rate and fees for the transaction.

Show child attributes

transaction.rateDetails.gridApiMultiplier

number<double>

required

The underlying multiplier from the mSATS to the receiving currency, including variable fees.

Example:

0.925

transaction.rateDetails.gridApiFixedFee

integer<int64>

required

The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents).

Required range: x >= 0

Example:

10

transaction.rateDetails.gridApiVariableFeeRate

number<double>

required

The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount.

Example:

0.003

transaction.rateDetails.gridApiVariableFeeAmount

number<int64>

required

The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate.

Required range: x >= 0

Example:

30

transaction.failureReason

enum<string>

If the transaction failed, this field provides the reason for failure.

Available options:

LNURLP_FAILED,

PAY_REQUEST_FAILED,

PAYMENT_APPROVAL_WEBHOOK_ERROR,

PAYMENT_APPROVAL_TIMED_OUT,

OFFRAMP_FAILED,

MISSING_MANDATORY_PAYEE_DATA,

QUOTE_EXPIRED,

QUOTE_EXECUTION_FAILED

requestedReceiverCustomerInfoFields

object[]

Information required by the sender's VASP about the recipient. Platform must provide these in the 200 OK response if approving. Note that this only includes fields which Grid does not already have from initial customer registration.

Show child attributes

requestedReceiverCustomerInfoFields.name

enum<string>

required

Name of a type of field containing info about a platform's customer or counterparty customer.

Available options:

FULL_NAME,

BIRTH_DATE,

NATIONALITY,

PHONE_NUMBER,

EMAIL,

POSTAL_ADDRESS,

TAX_ID,

REGISTRATION_NUMBER,

USER_TYPE,

COUNTRY_OF_RESIDENCE,

ACCOUNT_IDENTIFIER,

FI_LEGAL_ENTITY_NAME,

FI_ADDRESS,

PURPOSE_OF_PAYMENT,

ULTIMATE_INSTITUTION_COUNTRY,

IDENTIFIER

Example:

"FULL_NAME"

requestedReceiverCustomerInfoFields.mandatory

boolean

required

Whether the field is mandatory

Example:

true

Response

Webhook received successfully. For PENDING transactions, this indicates approval to proceed with the payment. If requestedReceiverCustomerInfoFields were present in the webhook request, the corresponding fields for the recipient must be included in this response in the receiverCustomerInfo object.

receiverCustomerInfo

object

Information about the recipient, provided by the platform if requested in the webhook via requestedReceiverCustomerInfoFields and the payment is approved.

Using the API

API documentation

Incoming payment webhook and approval mechanism

Authentication

Payment Approval Flow

Authorizations

Body

Response