Sign in

v5

OpenAPI 3.1.0Proprietary2026-08-011476181.4 MB
Webhooks

Incoming payment webhook and approval mechanism

Webhook that is called when an incoming payment is received by a customer's UMA address. This endpoint should be implemented by clients of the Grid API.

Authentication

The webhook includes a signature in the X-Grid-Signature header that allows you to verify that the webhook was sent by Grid. To verify the signature:

  1. Get the Grid public key provided to you during integration
  2. Decode the base64 signature from the header
  3. Create a SHA-256 hash of the request body
  4. 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.

Payment Approval Flow

When a transaction has status: "PENDING", this webhook serves as an approval mechanism:

  1. The client should check the counterpartyInformation against their requirements
  2. To APPROVE the payment synchronously, return a 200 OK response
  3. To REJECT the payment, return a 403 Forbidden response with an Error object
  4. To request more information, return a 422 Unprocessable Entity with specific missing fields
  5. To process the payment asynchronously, return a 202 Accepted response and then call the /transactions/{transactionId}/approve or /transactions/{transactionId}/reject endpoint within 5 seconds. Note that synchronous approval/rejection is preferred where possible.

The Grid system will proceed or cancel the payment based on your response.

For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational.

postWebhookincoming-payment

Payload

idstring required

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

type'INCOMING_PAYMENT.PENDING' | 'INCOMING_PAYMENT.COMPLETED' | 'INCOMING_PAYMENT.FAILED' | 'INCOMING_PAYMENT.REFUND_PENDING' | 'INCOMING_PAYMENT.REFUND_COMPLETED' | 'INCOMING_PAYMENT.REFUND_FAILED' required

Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status.

timestampstring date-time required

ISO 8601 timestamp of when the webhook was sent

Example payload

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "timestamp": "2025-08-15T14:32:00Z",
  "data": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "destination": {
      "destinationType": "ACCOUNT",
      "currency": "EUR",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "sentAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "exchangeRate": 1.08,
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "refund": {
      "reference": "UMA-Q12345-REFUND",
      "initiatedAt": "2025-08-15T14:30:00Z",
      "settledAt": "2025-08-15T14:35:00Z",
      "status": "COMPLETED",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "currency": "USD",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "fees": 10,
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF",
      "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
    },
    "requestedReceiverCustomerInfoFields": [
      {
        "name": "FULL_NAME",
        "mandatory": 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.

receiverCustomerInfoobject

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