Create Payment

POST/payments/new

Description

Create a new payment request. This endpoint initiates a transaction by generating a unique payment request. Once created, it returns essential details such as a payment ID and the URL for the customer to make the payment.

Headers

Header	Description	Required
Content-Type	application/json	yes
x-api-key	Your API key	yes

Request Body

Required Fields

Name	Type	Description
totalAmount	number	Amount to be paid.
fiatCurrency	string	Currency in ISO code. Only UYU, USD, EUR, and ARS accepted.

Optional Fields

Name	Type	Description
customUsdPriceRate	number \| null	Required if currency is UYU or ARS. Must be null for USD and EUR.
externalReferenceId	string \| null	Reference ID for external integration.
posId	string \| null	Use only with Physical integration, if PoS is configured.
callbackUrl	string \| null	Use only with Online integration. Redirect URL after payment.
items	array \| null	Array of item objects for invoice details. Maximum 20 items.
expiresIn	number \| null	Payment expiration time in minutes. Must be between 1 and 1440 (24 hours).
invoiceCreatedAt	string \| null	UTC timestamp in ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ
invoiceDiscount	string \| null	Discount applied at invoice level.
externalClientId	string \| null	External identifier for the client.
customerEmail	string \| null	Customer's email address.

Items Schema

Each item in the items array can contain:

Name	Type	Description	Required
name	string	Item name	yes
quantity	number	Quantity of the item. Must be at least 1.	yes
unitPrice	number	Price per unit. Must be at least 0.01.	yes
description	string	Item description	no
discount	number	Discount applied to this item. Note: If provided, subtotal is required.	no
subtotal	number	Subtotal for this item. Required when discount is provided.	no
externalProductId	string	External identifier for the product	no

⚠️

Calculation Validation: Grateful stores all item details and invoice information for display purposes only. The system does not validate mathematical relationships between item-level or invoice-level calculations. The payment will always charge the exact totalAmount specified, regardless of item details.

Example Request

const response = await fetch('https://merchant.grateful.me/api/payments/new', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<your-api-key>',
  },
  body: JSON.stringify({
    totalAmount: 50.0,
    fiatCurrency: 'USD',
    externalReferenceId: 'order-12345',
    customerEmail: '[email protected]',
    callbackUrl: 'https://yoursite.com/payment-complete',
    items: [
      {
        name: 'Coffee',
        quantity: 2,
        unitPrice: 15.0,
      },
      {
        name: 'Croissant',
        description: 'Freshly baked',
        quantity: 1,
        unitPrice: 20.0,
        externalProductId: 'croissant-001',
      },
    ],
  }),
});

Response

SUCCESSFUL PAYMENT CREATION (200)

{
  "id": "e0611550-0935-40f1-9cad-63096476207d",
  "recipient": "0x549A9021661a85B6BC51c07B3A451135848d0048",
  "fiatAmount": 50.0,
  "fiatCurrency": "USD",
  "customUsdPriceRate": null,
  "tokenAmount": null,
  "enabledTokens": {
    "DAI": [42161, 8453, 137, 10],
    "USDC": [56, 8453, 42161, 137, 10],
    "USDT": [137, 42161, 56, 8453]
  },
  "selectedToken": null,
  "merchantId": "2aab0e4a-cb50-44ac-88ef-8a5b79fd7d75",
  "selectedChainId": null,
  "depositAddress": null,
  "senderAddress": null,
  "expiresAt": "2025-09-09T03:57:43.053Z",
  "status": "AwaitingConfiguration",
  "error": null,
  "contractPaymentId": "298251156122803456481887845141481660541",
  "integrationId": 63,
  "createdAt": "2025-09-08T19:37:43.053Z",
  "updatedAt": "2025-09-08T19:37:43.054Z",
  "processing": false,
  "posId": null,
  "isYieldingFunds": false,
  "gratefulFee": null,
  "callbackUrl": "https://yoursite.com/payment-complete",
  "metadata": {
    "externalReferenceId": "order-12345",
    "externalClientId": null,
    "paymentItems": [
      {
        "id": "ab2813db-97b5-46b2-992b-3758366ee982",
        "name": "Coffee",
        "quantity": 2,
        "unitPrice": 15.0
      },
      {
        "id": "1e29d7f7-2f47-404c-8ddc-3d3650958e35",
        "name": "Croissant",
        "description": "Freshly baked",
        "quantity": 1,
        "unitPrice": 20.0,
        "externalProductId": "croissant-001"
      }
    ],
    "customerEmail": "[email protected]"
  },
  "merchant": {
    "id": "2aab0e4a-cb50-44ac-88ef-8a5b79fd7d75",
    "name": "Your Store",
    "avatarUrl": "https://example.com/avatar.png",
    "username": "yourstore",
    "country": "United States"
  },
  "url": "https://grateful.me/p/e0611550-0935-40f1-9cad-63096476207d",
  "fiatAmountInUSD": 50.0
}

Responses

Status	Description
200	Success
400	Bad Request - Invalid parameters