> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycashq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Charge Transaction

> Process card payments using the charge endpoint

## 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

<Tabs>
  <Tab title="Sandbox">
    ```http theme={null}
    POST https://api.sandbox.approvelygateway.com/api/v2/transactions/charge
    ```
  </Tab>

  <Tab title="Production">
    ```http theme={null}
    POST https://banking.cashqbot.com/api/v2/transactions/charge
    ```
  </Tab>
</Tabs>

## Authentication

<ParamField header="Authorization" type="string" required>
  Basic Authentication header with Base64 encoded `[API_KEY]:[PIN]`

  Format: `Basic [base64_credentials]`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Request Body

<ParamField body="amount" type="number" required>
  Transaction amount in dollars (e.g., `5` for \$5.00)
</ParamField>

<ParamField body="source" type="string" required>
  Nonce token obtained from card tokenization (e.g., `"nonce-pft4uav4cker5g8bk3db"`)
</ParamField>

<ParamField body="expiry_month" type="integer" required>
  Card expiry month (1-12)
</ParamField>

<ParamField body="expiry_year" type="integer" required>
  Card expiry year (e.g., `2028`)
</ParamField>

<ParamField body="billing_info" type="object" required>
  Customer billing information

  <Expandable title="Billing info properties">
    <ParamField body="first_name" type="string" required>
      Customer's first name
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Customer's last name
    </ParamField>

    <ParamField body="street" type="string" required>
      Street address
    </ParamField>

    <ParamField body="street2" type="string">
      Additional address line (apartment, suite, etc.)
    </ParamField>

    <ParamField body="city" type="string" required>
      City name
    </ParamField>

    <ParamField body="state" type="string" required>
      State/Province code (e.g., `"FL"`, `"CA"`)
    </ParamField>

    <ParamField body="zip" type="string" required>
      ZIP/Postal code
    </ParamField>

    <ParamField body="country" type="string" required>
      Country code (e.g., `"US"`)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="transaction_details" type="object">
  Optional transaction metadata for your internal tracking

  <Expandable title="Transaction details properties">
    <ParamField body="description" type="string">
      Transaction description
    </ParamField>

    <ParamField body="clerk" type="string">
      Clerk or employee identifier
    </ParamField>

    <ParamField body="terminal" type="string">
      Terminal identifier
    </ParamField>

    <ParamField body="client_ip" type="string">
      Customer's IP address
    </ParamField>

    <ParamField body="signature" type="string">
      Digital signature or reference
    </ParamField>

    <ParamField body="invoice_number" type="string">
      Your internal invoice number
    </ParamField>

    <ParamField body="po_number" type="string">
      Purchase order number
    </ParamField>

    <ParamField body="order_number" type="string">
      Your internal order number
    </ParamField>
  </Expandable>
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```javascript Node.js theme={null}
  const apiKey = 'your_api_key';
  const pin = 'your_pin';
  const credentials = Buffer.from(`${apiKey}:${pin}`).toString('base64');

  const chargeData = {
    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'
    }
  };

  const response = await fetch(
    'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${credentials}`
      },
      body: JSON.stringify(chargeData)
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests
  import base64
  import json

  api_key = 'your_api_key'
  pin = 'your_pin'
  credentials = base64.b64encode(f'{api_key}:{pin}'.encode()).decode()

  charge_data = {
      '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'
      }
  }

  response = requests.post(
      'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge',
      headers={
          'Content-Type': 'application/json',
          'Authorization': f'Basic {credentials}'
      },
      json=charge_data
  )

  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = 'your_api_key';
  $pin = 'your_pin';
  $credentials = base64_encode($apiKey . ':' . $pin);

  $chargeData = [
      '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'
      ]
  ];

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, 'https://api.sandbox.approvelygateway.com/api/v2/transactions/charge');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'Authorization: Basic ' . $credentials
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($chargeData));

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique transaction identifier
</ResponseField>

<ResponseField name="status" type="string">
  Transaction status (e.g., `"approved"`, `"declined"`)
</ResponseField>

<ResponseField name="amount" type="number">
  Transaction amount
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., `"USD"`)
</ResponseField>

<ResponseField name="card" type="object">
  Card information

  <Expandable title="Card properties">
    <ResponseField name="last_four" type="string">
      Last 4 digits of the card
    </ResponseField>

    <ResponseField name="card_type" type="string">
      Card brand (e.g., `"visa"`, `"mastercard"`)
    </ResponseField>

    <ResponseField name="expiry_month" type="integer">
      Card expiry month
    </ResponseField>

    <ResponseField name="expiry_year" type="integer">
      Card expiry year
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Transaction timestamp (ISO 8601 format)
</ResponseField>

<ResponseField name="authorization_code" type="string">
  Authorization code from payment processor
</ResponseField>

## Response Examples

<ResponseExample>
  ```json Success theme={null}
  {
    "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
    }
  }
  ```

  ```json Declined theme={null}
  {
    "id": "txn_1234567891",
    "status": "declined",
    "amount": 5.00,
    "currency": "USD",
    "error": {
      "code": "card_declined",
      "message": "The card was declined"
    },
    "card": {
      "last_four": "0002",
      "card_type": "visa"
    },
    "created_at": "2024-01-15T10:31:00Z"
  }
  ```

  ```json Invalid Nonce theme={null}
  {
    "error": {
      "code": "invalid_nonce",
      "message": "The provided nonce is invalid or has expired"
    }
  }
  ```
</ResponseExample>

## 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

<Steps>
  <Step title="Tokenize card">
    Use the tokenization form to get a nonce token from the customer's card data

    ```javascript theme={null}
    const nonce = await tokenizeCard(cardData);
    ```
  </Step>

  <Step title="Send nonce to server">
    Send the nonce from your frontend to your backend server

    ```javascript theme={null}
    const response = await fetch('/api/process-payment', {
      method: 'POST',
      body: JSON.stringify({ nonce, amount, billingInfo })
    });
    ```
  </Step>

  <Step title="Process charge">
    Your server calls the Approvely charge endpoint with the nonce

    ```javascript theme={null}
    const result = await chargeCard(nonce, amount, billingInfo);
    ```
  </Step>

  <Step title="Handle response">
    Check the transaction status and update your order accordingly

    ```javascript theme={null}
    if (result.status === 'approved') {
      fulfillOrder(orderId);
    } else {
      handleDecline(result.error);
    }
    ```
  </Step>
</Steps>

## Error Handling

<AccordionGroup>
  <Accordion title="card_declined">
    **Cause:** Card issuer declined the transaction

    **Solution:**

    * Ask customer to contact their bank
    * Request alternative payment method
    * Verify billing information is correct
  </Accordion>

  <Accordion title="invalid_nonce">
    **Cause:** Nonce token is invalid or expired

    **Solution:**

    * Re-tokenize the card to get a new nonce
    * Ensure nonce is used immediately after generation
    * Don't reuse nonces
  </Accordion>

  <Accordion title="insufficient_funds">
    **Cause:** Card has insufficient funds

    **Solution:**

    * Request different payment method
    * Ask customer to use another card
  </Accordion>

  <Accordion title="invalid_card">
    **Cause:** Card number or details are invalid

    **Solution:**

    * Verify card number is correct
    * Check expiry date is valid
    * Ensure CVV is correct
  </Accordion>

  <Accordion title="authentication_error">
    **Cause:** Invalid API credentials

    **Solution:**

    * Verify API Key and PIN are correct
    * Check Base64 encoding is proper
    * Ensure using correct environment credentials
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Nonce Immediately" icon="clock">
    Process charges immediately after receiving the nonce token
  </Card>

  <Card title="Validate Before Charging" icon="check">
    Validate amount and billing info before calling the API
  </Card>

  <Card title="Handle All Statuses" icon="list">
    Account for approved, declined, pending, and failed statuses
  </Card>

  <Card title="Log Transactions" icon="file-lines">
    Keep detailed logs of all charge attempts for reconciliation
  </Card>

  <Card title="Secure Credentials" icon="lock">
    Never expose API credentials on the client side
  </Card>

  <Card title="Use HTTPS Only" icon="shield">
    Always make API requests over HTTPS
  </Card>
</CardGroup>

## 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`

## Related Documentation

<CardGroup cols={2}>
  <Card title="Tokenization" icon="shield" href="/payin/tokenization">
    Learn how to tokenize card data
  </Card>

  <Card title="Authentication" icon="key" href="/payin/authentication">
    Set up API authentication
  </Card>
</CardGroup>