Create payment intent

Create a new payment intent between source and destination external accounts.

The system evaluates each active provider’s capabilities against the external account metadata (currency, account type, rail, country) to determine which providers can handle the payment. If providerId is specified, it must be among the eligible candidates — otherwise a 400 error is returned. If omitted, the first eligible provider is selected.

The selected provider determines which compliance requirements (KYC/onboarding steps) apply. Different providers may have different compliance flows.

Auto-Complete: For returning customers who have already completed compliance requirements, the API will automatically create a transaction and return deposit instructions immediately, skipping the onboarding workflow. In this case, transaction will be present and frontendUrl will be null.

POST /intent

Create payment intent

cURL

curl --request POST \
  --url https://api.gnosisramp.io/v1/intent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "srcExternalAccountId": "ext_acc_src_123",
  "destExternalAccountId": "ext_acc_dest_456",
  "amount": "100.50",
  "autoExecute": false,
  "redirectUrl": "https://example.com/callback",
  "providerId": "provider_123"
}
'

201

{
  "intent": {
    "id": "<string>",
    "src": {
      "id": "ext_acc_12345",
      "type": "BANK_ACCOUNT",
      "currencyId": "usd-currency-id",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "metadata": {},
      "label": "Personal Checking Account",
      "customerId": "customer-123",
      "currency": {
        "id": "usd-currency-id",
        "ticker": "USDC",
        "name": "USD Coin",
        "code": "USDC_ETH",
        "decimals": 6,
        "type": "FIAT",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    },
    "dest": {
      "id": "ext_acc_12345",
      "type": "BANK_ACCOUNT",
      "currencyId": "usd-currency-id",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "metadata": {},
      "label": "Personal Checking Account",
      "customerId": "customer-123",
      "currency": {
        "id": "usd-currency-id",
        "ticker": "USDC",
        "name": "USD Coin",
        "code": "USDC_ETH",
        "decimals": 6,
        "type": "FIAT",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    },
    "status": "PENDING",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "currentRequirementCode": "<string>",
    "expiredAt": "2023-11-07T05:31:56Z",
    "transferAmount": {
      "amount": "100.50",
      "currencyCode": "USD"
    },
    "mmPlan": {
      "id": "mm_plan_123",
      "type": "ONRAMP",
      "providerAccountId": "provider_acc_123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "providerAccount": {
        "id": "<string>",
        "providerCode": "NOAH",
        "providerName": "Noah"
      }
    },
    "compliancePlan": {
      "id": "compliance_plan_123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "currentStepCode": "KYC_VERIFICATION",
      "steps": [
        {
          "id": "step_123",
          "code": "KYC_VERIFICATION",
          "description": "Complete KYC verification",
          "createdAt": "2024-01-01T00:00:00.000Z",
          "updatedAt": "2024-01-01T00:00:00.000Z",
          "metadata": {},
          "complianceEdge": {
            "id": "<string>"
          }
        }
      ]
    },
    "redirectUrl": "<string>",
    "autoExecute": true
  },
  "frontendUrl": "<string>",
  "workflowId": "<string>",
  "transaction": {
    "id": "txn_123",
    "intentId": "intent_123",
    "status": "PENDING",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "providerReference": "noah_txn_abc123",
    "lastActivityAt": "2024-01-01T00:00:00.000Z",
    "context": {}
  }
}

Authorizations

Authorization · string · header · required

GnosisRamp JWT bearer token for authenticated customer requests

Body

application/json

Request to create a payment intent

srcExternalAccountId · string · required

Source external account identifier

Example:

"ext_acc_src_123"

destExternalAccountId · string · required

Destination external account identifier

Example:

"ext_acc_dest_456"

amount · string · required

Transfer amount as a decimal string (not a number to avoid precision issues)

Example:

"100.50"

autoExecute · boolean · default: false

When true, automatically execute the transaction after compliance completes (skips the manual execute step)

redirectUrl · string<uri> | null

Optional redirect URL after intent completion

Example:

"https://example.com/callback"

providerId · string

Optional preferred provider ID. Must be a valid candidate for the payment path — i.e., the provider must support the currencies, rail, country, and account types of the external accounts. Use GET /currencies/supported or GET /providers to discover available provider IDs.

Maximum string length: 255

Example:

"provider_123"

Response

201

application/json

Intent created successfully

Intent creation response

intent · object · required

Show child attributes

frontendUrl · string<uri> | null · required

URL for the hosted onboarding/compliance frontend (null if auto-completed)

workflowId · string | null · required

Workflow identifier

transaction · object

Money movement transaction if auto-completed

Show child attributes