Charge Transaction

{
  "status": "Approved",
  "status_code": "A",
  "reference_number": 46364493,
  "auth_code": "034674",
  "auth_amount": 100,
  "card_type": "Visa",
  "last_4": "6713",
  "avs_result": "Address: No Match & 5 Digit Zip: Match",
  "avs_result_code": "NYZ",
  "cvv2_result": "Match",
  "cvv2_result_code": "M",
  "version": "2.0.0",
  "transaction": {
    "id": 46364493,
    "created_at": "2025-09-09T09:48:23.000Z",
    "status_details": {
      "status": "captured"
    },
    "amount_details": {
      "amount": 100,
      "subtotal": 100,
      "tax": 0,
      "tax_percent": 0,
      "shipping": 0,
      "discount": 0,
      "tip": 0,
      "surcharge": 0,
      "original_requested_amount": 100,
      "original_authorized_amount": 100
    },
    "card_details": {
      "card_type": "Visa",
      "last4": "6713",
      "bin": "423223",
      "expiry_month": 1,
      "expiry_year": 2026,
      "auth_code": "034674",
      "avs_result": "Address: No Match & 5 Digit Zip: Match",
      "avs_result_code": "NYZ",
      "avs_street": "1234 Main Street",
      "avs_zip": "12345",
      "cvv_result": "Match",
      "cvv_result_code": "M",
      "cavv_result": "N/A",
      "cavv_result_code": null,
      "bin_details": {
        "type": "D"
      },
      "name": null
    },
    "billing_info": {
      "first_name": "John",
      "last_name": "Smith",
      "street": "1234 Main Street",
      "street2": "Apt 2E",
      "city": "Springfield",
      "state": "CA",
      "zip": "12345",
      "country": "US",
      "phone": "5551234567"
    },
    "shipping_info": {
      "first_name": null,
      "last_name": null,
      "street": null,
      "street2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone": null
    },
    "transaction_details": {
      "type": "charge",
      "source": "BrightProd",
      "batch_id": 3209846,
      "description": null,
      "order_number": null,
      "invoice_number": null,
      "po_number": null,
      "reference_number": null,
      "clerk": null,
      "terminal": null,
      "client_ip": null,
      "schedule_id": null
    },
    "customer": {
      "customer_id": null,
      "identifier": null,
      "email": null,
      "fax": null
    },
    "custom_fields": {},
    "settled_date": null
  }
}

POST

api

transactions

charge

{
  "status": "Approved",
  "status_code": "A",
  "reference_number": 46364493,
  "auth_code": "034674",
  "auth_amount": 100,
  "card_type": "Visa",
  "last_4": "6713",
  "avs_result": "Address: No Match & 5 Digit Zip: Match",
  "avs_result_code": "NYZ",
  "cvv2_result": "Match",
  "cvv2_result_code": "M",
  "version": "2.0.0",
  "transaction": {
    "id": 46364493,
    "created_at": "2025-09-09T09:48:23.000Z",
    "status_details": {
      "status": "captured"
    },
    "amount_details": {
      "amount": 100,
      "subtotal": 100,
      "tax": 0,
      "tax_percent": 0,
      "shipping": 0,
      "discount": 0,
      "tip": 0,
      "surcharge": 0,
      "original_requested_amount": 100,
      "original_authorized_amount": 100
    },
    "card_details": {
      "card_type": "Visa",
      "last4": "6713",
      "bin": "423223",
      "expiry_month": 1,
      "expiry_year": 2026,
      "auth_code": "034674",
      "avs_result": "Address: No Match & 5 Digit Zip: Match",
      "avs_result_code": "NYZ",
      "avs_street": "1234 Main Street",
      "avs_zip": "12345",
      "cvv_result": "Match",
      "cvv_result_code": "M",
      "cavv_result": "N/A",
      "cavv_result_code": null,
      "bin_details": {
        "type": "D"
      },
      "name": null
    },
    "billing_info": {
      "first_name": "John",
      "last_name": "Smith",
      "street": "1234 Main Street",
      "street2": "Apt 2E",
      "city": "Springfield",
      "state": "CA",
      "zip": "12345",
      "country": "US",
      "phone": "5551234567"
    },
    "shipping_info": {
      "first_name": null,
      "last_name": null,
      "street": null,
      "street2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone": null
    },
    "transaction_details": {
      "type": "charge",
      "source": "BrightProd",
      "batch_id": 3209846,
      "description": null,
      "order_number": null,
      "invoice_number": null,
      "po_number": null,
      "reference_number": null,
      "clerk": null,
      "terminal": null,
      "client_ip": null,
      "schedule_id": null
    },
    "customer": {
      "customer_id": null,
      "identifier": null,
      "email": null,
      "fax": null
    },
    "custom_fields": {},
    "settled_date": null
  }
}

Overview

The charge endpoint processes a payment using a nonce token obtained from card tokenization. This endpoint debits the customer’s card and credits your merchant account.

Endpoint

Sandbox
Production

POST https://api.sandbox.approvelygateway.com/api/v2/transactions/charge

Authentication

Authorization

string

required

Basic Authentication header with Base64 encoded [API_KEY]:[PIN]Format: Basic [base64_credentials]

Content-Type

string

required

Must be application/json

Request Body

amount

number

required

Transaction amount in dollars (e.g., 5 for $5.00)

source

string

required

Nonce token obtained from card tokenization (e.g., "nonce-pft4uav4cker5g8bk3db")

expiry_month

integer

required

Card expiry month (1-12)

expiry_year

integer

required

Card expiry year (e.g., 2028)

billing_info

object

required

Customer billing information

Show Billing info properties

first_name

string

required

Customer’s first name

last_name

string

required

Customer’s last name

street

string

required

Street address

street2

string

Additional address line (apartment, suite, etc.)

city

string

required

City name

state

string

required

State/Province code (e.g., "FL", "CA")

zip

string

required

ZIP/Postal code

country

string

required

Country code (e.g., "US")

transaction_details

object

Optional transaction metadata for your internal tracking

Show Transaction details properties

description

string

Transaction description

clerk

string

Clerk or employee identifier

terminal

string

Terminal identifier

client_ip

string

Customer’s IP address

signature

string

Digital signature or reference

invoice_number

string

Your internal invoice number

po_number

string

Purchase order number

order_number

string

Your internal order number

Request Example

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  -d '{
    "amount": 100,
    "source": "nonce-6d7a7yelkl2pjokjs6rq",
    "expiry_month": 1,
    "expiry_year": 2026,
    "billing_info": {
      "first_name": "John",
      "last_name": "Smith",
      "street": "1234 Main Street",
      "street2": "Apt 2E",
      "city": "Springfield",
      "state": "CA",
      "zip": "12345",
      "country": "US",
      "phone": "5551234567"
    }
  }' \
  'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge'

Response

string

Unique transaction identifier

status

string

Transaction status (e.g., "approved", "declined")

amount

number

Transaction amount

currency

string

Currency code (e.g., "USD")

card

object

Card information

Show Card properties

last_four

string

Last 4 digits of the card

card_type

string

Card brand (e.g., "visa", "mastercard")

expiry_month

integer

Card expiry month

expiry_year

integer

Card expiry year

created_at

string

Transaction timestamp (ISO 8601 format)

authorization_code

string

Authorization code from payment processor

Response Examples

{
  "status": "Approved",
  "status_code": "A",
  "reference_number": 46364493,
  "auth_code": "034674",
  "auth_amount": 100,
  "card_type": "Visa",
  "last_4": "6713",
  "avs_result": "Address: No Match & 5 Digit Zip: Match",
  "avs_result_code": "NYZ",
  "cvv2_result": "Match",
  "cvv2_result_code": "M",
  "version": "2.0.0",
  "transaction": {
    "id": 46364493,
    "created_at": "2025-09-09T09:48:23.000Z",
    "status_details": {
      "status": "captured"
    },
    "amount_details": {
      "amount": 100,
      "subtotal": 100,
      "tax": 0,
      "tax_percent": 0,
      "shipping": 0,
      "discount": 0,
      "tip": 0,
      "surcharge": 0,
      "original_requested_amount": 100,
      "original_authorized_amount": 100
    },
    "card_details": {
      "card_type": "Visa",
      "last4": "6713",
      "bin": "423223",
      "expiry_month": 1,
      "expiry_year": 2026,
      "auth_code": "034674",
      "avs_result": "Address: No Match & 5 Digit Zip: Match",
      "avs_result_code": "NYZ",
      "avs_street": "1234 Main Street",
      "avs_zip": "12345",
      "cvv_result": "Match",
      "cvv_result_code": "M",
      "cavv_result": "N/A",
      "cavv_result_code": null,
      "bin_details": {
        "type": "D"
      },
      "name": null
    },
    "billing_info": {
      "first_name": "John",
      "last_name": "Smith",
      "street": "1234 Main Street",
      "street2": "Apt 2E",
      "city": "Springfield",
      "state": "CA",
      "zip": "12345",
      "country": "US",
      "phone": "5551234567"
    },
    "shipping_info": {
      "first_name": null,
      "last_name": null,
      "street": null,
      "street2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone": null
    },
    "transaction_details": {
      "type": "charge",
      "source": "BrightProd",
      "batch_id": 3209846,
      "description": null,
      "order_number": null,
      "invoice_number": null,
      "po_number": null,
      "reference_number": null,
      "clerk": null,
      "terminal": null,
      "client_ip": null,
      "schedule_id": null
    },
    "customer": {
      "customer_id": null,
      "identifier": null,
      "email": null,
      "fax": null
    },
    "custom_fields": {},
    "settled_date": null
  }
}

Transaction Statuses

Status	Description	Action
`approved`	Transaction successful	Fulfill order
`declined`	Card declined by issuer	Request different payment method
`pending`	Transaction pending review	Wait for final status
`failed`	Transaction failed	Check error details and retry

Complete Payment Flow

Tokenize card

Use the tokenization form to get a nonce token from the customer’s card data

const nonce = await tokenizeCard(cardData);

Send nonce to server

Send the nonce from your frontend to your backend server

const response = await fetch('/api/process-payment', {
  method: 'POST',
  body: JSON.stringify({ nonce, amount, billingInfo })
});

Process charge

Your server calls the Approvely charge endpoint with the nonce

const result = await chargeCard(nonce, amount, billingInfo);

Handle response

Check the transaction status and update your order accordingly

if (result.status === 'approved') {
  fulfillOrder(orderId);
} else {
  handleDecline(result.error);
}

Error Handling

card_declined

Cause: Card issuer declined the transactionSolution:

Ask customer to contact their bank
Request alternative payment method
Verify billing information is correct

invalid_nonce

Cause: Nonce token is invalid or expiredSolution:

Re-tokenize the card to get a new nonce
Ensure nonce is used immediately after generation
Don’t reuse nonces

insufficient_funds

Cause: Card has insufficient fundsSolution:

Request different payment method
Ask customer to use another card

invalid_card

Cause: Card number or details are invalidSolution:

Verify card number is correct
Check expiry date is valid
Ensure CVV is correct

authentication_error

Cause: Invalid API credentialsSolution:

Verify API Key and PIN are correct
Check Base64 encoding is proper
Ensure using correct environment credentials

Best Practices

Use Nonce Immediately

Process charges immediately after receiving the nonce token

Validate Before Charging

Validate amount and billing info before calling the API

Handle All Statuses

Account for approved, declined, pending, and failed statuses

Log Transactions

Keep detailed logs of all charge attempts for reconciliation

Secure Credentials

Never expose API credentials on the client side

Use HTTPS Only

Always make API requests over HTTPS

Testing

Use these test scenarios in the sandbox:

Successful Charge

Card: 4111 1111 1111 1111
Expected: status: "approved"

Declined Card

Card: 4000 0000 0000 0002
Expected: status: "declined"

Insufficient Funds

Card: 4000 0000 0000 9995
Expected: status: "declined", error code insufficient_funds

Tokenization

Learn how to tokenize card data

Authentication

Set up API authentication

Card Tokenization

⌘I

Getting Started

Endpoints

Overview

Endpoint

Authentication

Request Body

Request Example

Response

Response Examples

Transaction Statuses

Complete Payment Flow

Error Handling

Best Practices

Use Nonce Immediately

Validate Before Charging

Handle All Statuses

Log Transactions

Secure Credentials

Use HTTPS Only

Testing

Successful Charge

Declined Card

Insufficient Funds

Tokenization

Authentication

Getting Started

Endpoints

​Overview

​Endpoint

​Authentication

​Request Body

​Request Example

​Response

​Response Examples

​Transaction Statuses

​Complete Payment Flow

​Error Handling

​Best Practices

Use Nonce Immediately

Validate Before Charging

Handle All Statuses

Log Transactions

Secure Credentials

Use HTTPS Only

​Testing

​Successful Charge

​Declined Card

​Insufficient Funds

​Related Documentation

Tokenization

Authentication

Overview

Endpoint

Authentication

Request Body

Request Example

Response

Response Examples

Transaction Statuses

Complete Payment Flow

Error Handling

Best Practices

Testing

Successful Charge

Declined Card

Insufficient Funds

Related Documentation