Skip to main content
POST
/
api
/
v2
/
transactions
/
charge
Charge Transaction
curl --request POST \
  --url https://api.example.com/api/v2/transactions/charge \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "amount": 123,
  "source": "<string>",
  "expiry_month": 123,
  "expiry_year": 123,
  "billing_info": {
    "first_name": "<string>",
    "last_name": "<string>",
    "street": "<string>",
    "street2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>"
  },
  "transaction_details": {
    "description": "<string>",
    "clerk": "<string>",
    "terminal": "<string>",
    "client_ip": "<string>",
    "signature": "<string>",
    "invoice_number": "<string>",
    "po_number": "<string>",
    "order_number": "<string>"
  }
}
'
{
  "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

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
​
transaction_details
object
Optional transaction metadata for your internal tracking

​
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

​
id
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
​
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

StatusDescriptionAction
approvedTransaction successfulFulfill order
declinedCard declined by issuerRequest different payment method
pendingTransaction pending reviewWait for final status
failedTransaction failedCheck error details and retry

​
Complete Payment Flow

1

Tokenize card

Use the tokenization form to get a nonce token from the customer’s card data
const nonce = await tokenizeCard(cardData);
2

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 })
});
3

Process charge

Your server calls the Approvely charge endpoint with the nonce
const result = await chargeCard(nonce, amount, billingInfo);
4

Handle response

Check the transaction status and update your order accordingly
if (result.status === 'approved') {
  fulfillOrder(orderId);
} else {
  handleDecline(result.error);
}

​
Error Handling

Cause: Card issuer declined the transactionSolution:
  • Ask customer to contact their bank
  • Request alternative payment method
  • Verify billing information is correct
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
Cause: Card has insufficient fundsSolution:
  • Request different payment method
  • Ask customer to use another card
Cause: Card number or details are invalidSolution:
  • Verify card number is correct
  • Check expiry date is valid
  • Ensure CVV is correct
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