Skip to main content

API: Request examples

Overview​

This documentation provides an overview of the Orders API endpoints, including requests and responses for creating orders, retrieving payment methods, and checking payment statuses.

The examples use shop ID 115 and the test environment (demo).

Order request with required parameters only​

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test01",
    "cost": {
      "amount": "56.00",
      "currency": "CLP"
    }
  },
  "paymentSettings": {
    "instrumentType": "card",
    "providerCode": "alps",
    "acquirerCode": "lyra"
  }
}'

Response

{
  "data": {
    "orderNumber": "test01",
    "paymentLink": "https://payment-page.demo.vertexgateway.com/payment?session-id=1ef20f70-779b-657a-a3d3-3b4b627a1f5a&page-id=854"
  }
}

Order request with all fields​

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test04",
    "cost": {
      "amount": "56.99",
      "currency": "PHP"
    }
  },
  "customer": {
    "customerId": "1",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "paymentSettings": {
    "instrumentType": "card",
    "providerCode": "alps",
    "acquirerCode": "lyra",
    "entryMode": "cnp",
    "dataEntryMode": "redirect",
    "autoCapture": true,
    "timeLimit": "2024-06-15T10:51:49.086Z",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    },
    "webhookUrl": "https://example.com/webhook"
  },
  "paymentPageDesign": {
    "alias": "default",
    "format": "redirect"
  }
}'

Response

{
  "data": {
    "orderNumber": "test04",
    "paymentLink": "https://payment-page.demo.vertexgateway.com/payment?session-id=i2g40f50-234b-567a-l4c5-1d6c4d527a5i&page-id=109"
  }
}

Creating an order with customer information / Updating existing customer information​

If you need to update the customer information with the corresponding customerId, simply pass the same customerId, specify the required fields for customer object (First Name, Last Name), and provide the updated customer information.

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test20",
    "cost": {
      "amount": "56.99",
      "currency": "PHP"
    }
  },
  "customer": {
    "customerId": "1",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "paymentSettings": {
    "instrumentType": "card",
    "providerCode": "alps",
    "acquirerCode": "lyra",
    "entryMode": "cnp",
    "dataEntryMode": "redirect",
    "autoCapture": true,
    "timeLimit": "2024-06-15T10:51:49.086Z",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    },
    "webhookUrl": "https://example.com/webhook"
  }
}'

Retrieve available payment methods for a shop​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/shops/115/payment-methods' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "cleo",
      "acquirerCode": "cleo",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "allowedCards": [],
      "transferType": "bank_wire",
      "dataEntryModes": ["redirect"],
      "currencies": ["CLP"],
      "regions": ["CL"]
    },
    {
      "providerCode": "alps",
      "acquirerCode": "lyra",
      "instrumentType": "card",
      "entryMode": "cnp",
      "dataEntryModes": ["redirect"],
      "allowedCards": ["visa"],
      "transferType": null,
      "currencies": ["CLP"],
      "regions": ["CL"]
    },
    {
      "providerCode": "connectpay",
      "acquirerCode": "gcash",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": ["h2h"],
      "allowedCards": [],
      "transferType": null,
      "currencies": ["CLP"],
      "regions": ["CL"]
    }
  ]
}

Check order status​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/order/115/test07' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "id": 800123,
    "shopId": 115,
    "orderNumber": "test07",
    "orderStatus": "cancelled",
    "cost": {
      "amount": "56",
      "currency": "CLP"
    },
    "timeLimit": "2024-06-02T15:45:46+00:00",
    "orderCreatedAt": "2024-06-02T15:30:46+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [],
    "customer": {
      "customerId": "cust123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com",
      "birthDate": null,
      "affiliatedId": null,
      "billingAddress": null
    },
    "description": null,
    "recurringPayments": null,
    "parentId": null,
    "reviewTimeout": 120,
    "statusCode": "1-08-01",
    "statusDescription": "Cancelled by merchant"
  }
}

The full list of response fields is described in the Get Order reference.

Complete Flow: Retrieve Methods, Create Order, Check Status​

For card payments​

Step 1: Retrieve payment methods​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/shops/115/payment-methods' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "paysage",
      "acquirerCode": "paysage",
      "instrumentType": "card",
      "entryMode": "cnp",
      "dataEntryModes": ["h2h"],
      "allowedCards": ["visa", "mastercard"],
      "transferType": null,
      "currencies": ["EUR"],
      "regions": ["GB"]
    },
    {
      "providerCode": "alps",
      "acquirerCode": "lyra",
      "instrumentType": "card",
      "entryMode": "cnp",
      "dataEntryModes": ["redirect"],
      "allowedCards": ["visa"],
      "transferType": null,
      "currencies": ["CLP"],
      "regions": ["CL"]
    },
    {
      "providerCode": "cleanpay",
      "acquirerCode": "cleanpay",
      "instrumentType": "card",
      "entryMode": "cnp",
      "dataEntryModes": ["redirect"],
      "allowedCards": ["visa", "mastercard"],
      "transferType": null,
      "currencies": ["EUR", "USD"],
      "regions": ["AM"]
    }
  ]
}

Step 2: Create order​

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test08",
    "cost": {
      "amount": "56.00",
      "currency": "EUR"
    }
  },
  "paymentSettings": {
    "instrumentType": "card",
    "providerCode": "paysage",
    "acquirerCode": "paysage",
    "entryMode": "cnp",
    "dataEntryMode": "h2h"
  }
}'

Response

{
  "data": {
    "orderNumber": "test08",
    "paymentLink": "https://payment-page.demo.vertexgateway.com/payment?session-id=a7d20f70-891b-123a-b4c3-9d3c4b627a1a&page-id=108"
  }
}

Step 3: Check order status​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/order/115/test08' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "id": 800124,
    "shopId": 115,
    "orderNumber": "test08",
    "orderStatus": "cancelled",
    "cost": {
      "amount": "56",
      "currency": "EUR"
    },
    "timeLimit": "2024-06-02T15:45:46+00:00",
    "orderCreatedAt": "2024-06-02T15:30:46+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [],
    "customer": {
      "customerId": "cust123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com",
      "birthDate": null,
      "affiliatedId": null,
      "billingAddress": null
    },
    "description": null,
    "recurringPayments": null,
    "parentId": null,
    "reviewTimeout": 120,
    "statusCode": "1-08-01",
    "statusDescription": "Cancelled by merchant"
  }
}

The full list of response fields is described in the Get Order reference.

For wallet payments​

Step 1: Retrieve payment methods​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/shops/115/payment-methods' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "connectpay",
      "acquirerCode": "gcash",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": ["h2h"],
      "allowedCards": [],
      "transferType": null,
      "currencies": ["PHP"],
      "regions": ["PH"]
    },
    {
      "providerCode": "dukpay",
      "acquirerCode": "grabpay",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": ["redirect"],
      "allowedCards": [],
      "transferType": null,
      "currencies": ["PHP"],
      "regions": ["PH"]
    }
  ]
}

Step 2: Create order​

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test11",
    "cost": {
      "amount": "56.00",
      "currency": "PHP"
    }
  },
  "paymentSettings": {
    "instrumentType": "wallet",
    "providerCode": "connectpay",
    "acquirerCode": "gcash",
    "dataEntryMode": "h2h"
  }
}'

Response

{
  "data": {
    "orderNumber": "test11",
    "paymentLink": "https://payment-page.demo.vertexgateway.com/payment?session-id=d7b20f80-456b-213a-g1c9-7d5c4b327a5d&page-id=111"
  }
}

Step 3: Check payment status​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/order/115/test11' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "id": 800125,
    "shopId": 115,
    "orderNumber": "test11",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56.00",
      "currency": "PHP"
    },
    "timeLimit": "2024-06-02T16:43:51+00:00",
    "orderCreatedAt": "2024-06-02T16:28:51+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [],
    "customer": {
      "customerId": "cust123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com",
      "birthDate": null,
      "affiliatedId": null,
      "billingAddress": null
    },
    "description": null,
    "recurringPayments": null,
    "parentId": null,
    "reviewTimeout": 120,
    "statusCode": null,
    "statusDescription": null
  }
}

The full list of response fields is described in the Get Order reference.

For bank transfer payments​

Step 1: Retrieve payment methods​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/shops/115/payment-methods' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "zippy",
      "acquirerCode": "zippy",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": ["redirect"],
      "allowedCards": [],
      "transferType": "bank_wire",
      "currencies": ["CLP"],
      "regions": ["CL"]
    },
    {
      "providerCode": "platcore",
      "acquirerCode": "platcore",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": ["redirect"],
      "allowedCards": [],
      "transferType": "sbp",
      "currencies": ["RUB"],
      "regions": ["RU"]
    }
  ]
}

Step 2: Create order​

Request

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "order": {
    "orderNumber": "test13",
    "cost": {
      "amount": "56.00",
      "currency": "CLP"
    }
  },
  "paymentSettings": {
    "instrumentType": "bank_transfer",
    "providerCode": "zippy",
    "acquirerCode": "zippy",
    "dataEntryMode": "redirect"
  }
}'

Response

{
  "data": {
    "orderNumber": "test13",
    "paymentLink": "https://payment-page.demo.vertexgateway.com/payment?session-id=f5d30f10-789b-657a-i3d7-4d3e4c827a8f&page-id=113"
  }
}

Step 3: Check payment status​

Request

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/order/115/test13' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "id": 800126,
    "shopId": 115,
    "orderNumber": "test13",
    "orderStatus": "in_progress",
    "cost": {
      "amount": "56",
      "currency": "CLP"
    },
    "timeLimit": "2024-06-02T16:50:50+00:00",
    "orderCreatedAt": "2024-06-02T16:35:50+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [],
    "customer": {
      "customerId": "cust123",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": "+1234567890",
      "email": "john.doe@example.com",
      "birthDate": null,
      "affiliatedId": null,
      "billingAddress": null
    },
    "description": null,
    "recurringPayments": null,
    "parentId": null,
    "reviewTimeout": 120,
    "statusCode": null,
    "statusDescription": null
  }
}

The full list of response fields is described in the Get Order reference.

Complete Flow: CryptoWallet​

Step 1: Retrieve payment methods​

Request

curl -L 'https://gateway.demo.vertexgateway.com/api/v1/shops/105/payment-methods' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "crypto2b",
      "acquirerCode": "crypto2b",
      "instrumentType": "crypto_wallet",
      "entryMode": null,
      "dataEntryModes": ["h2h"],
      "allowedCards": [],
      "currencies": [],
      "transferType": null,
      "transferTypes": null,
      "regions": ["AU"]
    }
  ]
}

Step 2: Create an Order​

The crypto wallet is created through the Create Order endpoint — pass the customer and the cryptocurrency the customer will pay with. You can pass an existing customerId in customer, or the customer's data inline as shown below.

Request

curl -L 'https://gateway.demo.vertexgateway.com/api/v1/order' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": "105",
  "order": {
    "orderNumber": "ORD-crypto-001",
    "cost": {
      "amount": "0.0006",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "paymentSettings": {
    "providerCode": "crypto2b",
    "instrumentType": "crypto_wallet",
    "webhookUrl": "https://example.com",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}'

Response

{
  "data": {
    "orderNumber": "ORD-crypto-001",
    "paymentLink": "https://gateway.demo.vertexgateway.com/payment/019489b4-c004-7218-bbad-f77335ad3be9"
  }
}

Send the customer to paymentLink: the wallet address and its QR code are shown there. The recipientCryptoAddress field on the order is populated only after a transfer arrives and the payment is created.

note

The amount you pass is the expected amount. The customer can transfer any amount, and each transfer arrives as a separate transaction with the actual amount received.

Step 3: Callback​

If the customer transfers funds to the crypto wallet address, the merchant receives a callback with the orderStatus set to completed.

note

The callback reports cost.currency in the asset_code form (USDT_TRX), not the currency + tokenStandard notation used when creating the order (USDT + TRC20). Both denote the same asset.

{
  "data": {
    "id": 63,
    "shopId": 105,
    "orderNumber": "ORD-crypto-001",
    "orderStatus": "completed",
    "cost": {
      "amount": "0.000600",
      "currency": "USDT_TRX"
    },
    "timeLimit": "2025-01-21T16:46:51+00:00",
    "orderCreatedAt": "2025-01-21T16:31:51+00:00",
    "orderPaidAt": null,
    "autoCapture": true,
    "payments": [
      {
        "paymentId": "63",
        "paymentType": "order_by_webhook",
        "parentPayment": null,
        "cost": {
          "amount": "0.000600",
          "currency": "USDT_TRX"
        },
        "acquirer": {
          "code": "crypto2b"
        },
        "provider": {
          "code": "crypto2b"
        },
        "instrumentType": "crypto_wallet",
        "paymentStatus": {
          "status": "completed",
          "details": null
        },
        "paymentDetails": {
          "senderCryptoAddress": null,
          "recipientCryptoAddress": "TXYZaBcDeFgHiJkLmNoPqRsTuVwXyZ12345",
          "txHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
        },
        "providerPaymentId": "318",
        "transactionId": "173736484600000053"
      }
    ],
    "customer": {
      "customerId": "019489b4-c004-7218-bbad-f77335ad3be9",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "phone": null,
      "email": "john.doe@example.com"
    }
  }
}