Skip to main content

Quick Start

This guide walks you through making your first API call to the NetValve Payment Gateway. By the end, you will have processed a test Sale transaction in the sandbox environment.

Prerequisites​

Before you begin, make sure you have sandbox details from the NetValve team:

  • API credentials — your API Key (netvalve-api-key) and Client ID (netvalve-client-id)
  • A configured MID — your merchant ID (netvalveMidId) assigned during onboarding
tip

Don't have credentials yet? Contact the NetValve team to get set up with a sandbox account.

Step 1 — Authenticate​

All API requests must include your API Key and Client ID in the headers:

netvalve-api-key: YOUR_API_KEY
netvalve-client-id: YOUR_CLIENT_ID

For full details, see the API Authentication guide.

Step 2 — Make a test Sale transaction​

A Sale combines authorization and capture in one step — funds are taken from the cardholder immediately. Send a POST request to the /sale endpoint using the sandbox URL.

cURL
curl -X POST https://payment-api.uat.sandbox-netvalve.com/sale \
  -H "Content-Type: application/json" \
  -H "netvalve-api-key: YOUR_API_KEY" \
  -H "netvalve-client-id: YOUR_CLIENT_ID" \
  -d '{
    "amount": 1.00,
    "currency": "USD",
    "cardNumber": "4012000098765439",
    "cardExpireMonth": "12",
    "cardExpireYear": "2030",
    "cardSecurityCode": "123",
    "cardHolderName": "John Doe",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerEmail": "docs@netvalve.com",
    "orderDesc": "Test order",
    "netvalveMidId": "{{netvalveMidId}}"
  }'
note

The card number 4012000098765439 is a test card. See Test Cards for more options.

Step 3 — Check the response​

A successful transaction returns a JSON response like this:

200 OK
{
  "traceID": "03a9c205-1e49-4a0b-be47-12b5d6198477",
  "responseTimestamp": "2026-02-25T10:18:28.494+00:00",
  "transactionID": 88852,
  "responseCode": "GTW_1000",
  "responseMessage": "Transaction Approved/ Request Successful.",
  "responseCodeType": "APPROVED",
  "paymentMethod": "CARD",
  "cardNumber": "401200******5439",
  "cardExpiryMonth": "12",
  "cardExpiryYear": "2030",
  "cardType": "VISA",
  "bankTransactionId": "605610502689",
  "authCode": "TAS389",
  "netvalveMidId": ".....",
  "processor": "TSYS",
  "amount": 1.00,
  "currency": "USD",
  "transactionType": "SALE"
}

Key fields to check:

FieldDescription
responseCodeTypeAPPROVED means the transaction succeeded.
responseCodeGateway response code — GTW_1000 indicates approval.
transactionIDUnique identifier for this transaction. Use it for refunds, inquiries, etc.
traceIDRequest trace ID, useful for debugging with NetValve support.
warning

If responseCodeType is not APPROVED, check the responseCode and responseMessage fields. See Error Codes for a full list.

Step 4 — Verify with the Inquiry API​

You can confirm the transaction status at any time by calling the Inquiry endpoint:

cURL
curl -X POST https://payment-api.uat.sandbox-netvalve.com/inquiry \
  -H "Content-Type: application/json" \
  -H "netvalve-api-key: YOUR_API_KEY" \
  -H "netvalve-client-id: YOUR_CLIENT_ID" \
  -d '{
    "transactionId": 18747
  }'

Environments​

EnvironmentBase URL
Sandbox / UAThttps://payment-api.uat.sandbox-netvalve.com
Productionhttps://api.netvalve.com

For HPP URLs, webhook IPs, merchant identifier types (netvalveMidId vs midId vs siteId), and other environment details, see Environments & Identifiers.

danger

Never use real card numbers in the sandbox environment. Always use test cards.

What's next?​

Now that you've made your first transaction, explore these guides: