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

# Step-by-step "Make a Payment" example

> Learn how to process a payment with a real-world e-commerce scenario. Understand what happens behind the scenes when you charge a customer.

Let's walk through processing a payment using a real-world scenario: a customer buying a product from your online store. This example shows you how to charge a customer's card and understand what happens behind the scenes.

## Before You Start

Before initiating a payment request, make sure your account is properly configured with:

* A **supported payment processor** (like WorldPay, Adyen, Nuvei, TSYS) that's been set up in your merchant account
* A valid **static token** that you'll include in the `x-revolv3-token` request header for authentication

If you haven't set these up yet, check out [Authentication](/docs/authentication-security/merchant-access-token) first.

## Real-World Scenario: E-Commerce Checkout

Imagine a customer named John Doe is buying a \$1.03 product from your online store. They've entered their card information and clicked "Complete Purchase." Here's what happens:

1. **Your application collects** the customer's payment details (card number, billing address, amount)
2. **You send a request** to Revolv3 to process the payment
3. **Revolv3 routes the request** to a payment processor, which checks with the bank
4. **The bank approves or declines** the transaction
5. **You receive a response** telling you whether the payment succeeded

The whole process typically takes 2-3 seconds. If approved, the money is authorized (held) immediately, though it may take a few days to actually settle into your bank account.

## API Endpoint

Use the following endpoint to process a payment:

```
POST {{Api Root}}/api/payments/sale
```

Replace `{{Api Root}}` with:

* **Sandbox**: `api-sandbox.revolv3.com` (for testing)
* **Production**: `api.revolv3.com` (for live transactions)

## Sample Request: Charging a Customer

Here's what a payment request looks like for our example scenario:

<CodeGroup>
  ```bash bash theme={null}
  {
    "NetworkProcessing": {
      "ProcessingType": "initialInstallment",
      "OriginalNetworkTransactionId": null
    },
    "CustomerId": null,
    "PaymentMethod": {
      "BillingAddress": {
        "AddressLine1": "381 Forest Ave. Suite C",
        "City": "Laguna Beach",
        "State": "CA",
        "PostalCode": "92651",
        "Country": "USA"
      },
      "BillingFullName": "John Doe",
      "CreditCard": {
        "PaymentAccountNumber": "4444333322221111",
        "ExpirationDate": "0330",
        "SecurityCode": "737"
      }
    },
    "Invoice": {
      "MerchantInvoiceRefId": "ABC309500654810",
      "Amount": {
        "Value": 1.03
      }
    }
  }
  ```
</CodeGroup>

## Understanding the Request Fields

Let's break down what each part of the request does:

### NetworkProcessing

This tells Revolv3 how to classify the transaction, which affects how card networks process it:

* **`processingType`**:
  * `initialInstallment` — First payment in a series of installments (like "buy now, pay later")
  * `initialRecurring` — First payment in a subscription (like a monthly service)
  * `installment` — Subsequent installment payment
  * `recurring` — Subsequent subscription payment
  * For a one-time purchase, use `initialInstallment`
* **`originalNetworkTransactionId`**: Leave this `null` for new transactions. You'd use this if you're referencing a previous transaction (like a refund or follow-up payment).

### CustomerId

This is optional. If you already have a customer record in Revolv3, provide their ID here. If you leave it `null`, Revolv3 may create a new customer profile automatically (depending on your settings). This is useful if you want to track all of a customer's purchases together.

### PaymentMethod

This contains the customer's payment information:

* **`BillingAddress`**: The address associated with the credit card. This is used for fraud prevention—banks check if the address matches what they have on file.
* **`BillingFullName`**: The name on the credit card. Can be a person's name or a company name. Use standard ASCII characters only (letters, numbers, spaces, hyphens).
* **`CreditCard`**:
  * **`PaymentAccountNumber`**: The full credit card number (16 digits for most cards)
  * **`ExpirationDate`**: Format is MMYY (e.g., "0330" means March 2030)
  * **`SecurityCode`**: The CVV/CVC code (usually 3-4 digits on the back of the card)

> **Security Note**: Never store full card numbers or CVV codes in your database. Once you process a payment, you can store the `paymentMethodId` that Revolv3 returns and use that for future charges instead.

### Invoice

This represents the purchase being made:

* **`MerchantInvoiceRefId`**: Your internal order ID or invoice number. This helps you match Revolv3's response back to your system. Use something unique like "ORDER-12345" or a UUID.
* **`Amount.value`**: The amount to charge in USD (as a decimal number)

## What Happens Behind the Scenes

When you send this request, here's the flow:

1. **Revolv3 receives your request** and validates the format
2. **Revolv3 routes to a payment processor** (like WorldPay or Adyen) based on your merchant configuration
3. **The processor sends the request to the card network** (Visa, Mastercard, etc.)
4. **The card network checks with the bank** that issued the card:
   * Is the card valid?
   * Does the customer have enough funds?
   * Is the billing address correct?
   * Are there any fraud flags?
5. **The bank responds** with approval or decline
6. **The response flows back** through the network → processor → Revolv3 → your application

All of this happens in just a few seconds!

## Sample Response: Payment Approved

If everything goes well, you'll get a response like this:

<CodeGroup>
  ```bash bash theme={null}
  {
      "CustomerId": null,
      "InvoiceId": 185317,
      "MerchantInvoiceRefId": "ABC309500654810",
      "MerchantPaymentMethodRefId": null,
      "NetworkTransactionId": "538302743384089",
      "InvoiceStatus": "Paid",
      "InvoiceAttemptStatus": "Success",
      "Message": "Approved",
      "Amount": {
          "Currency": "USD",
          "Value": 1.03
      },
      "PaymentMethodId": 6061,
      "PaymentMethodTypeId": 1,
      "PaymentProcessor": "WorldPay",
      "ProcessorMerchantId": "10011222",
      "RawResponse": null,
      "PaymentMethodCreditCardDetails": {
          "BinNumber": "444433",
          "PaymentLast4Digit": "1111",
          "PaymentExpirationDate": "1130",
          "AccountUpdateMessage": null,
          "AccountUpdateDateTime": null
      },
      "ResponseMessage": null,
      "ResponseCode": "00"
  }
  ```
</CodeGroup>

## Understanding the Response

Here's what each field means and why it matters:

* **`invoiceId`**: Revolv3's unique identifier for this invoice. **Save this**—you'll need it for refunds, looking up the transaction, or customer support.
* **`merchantInvoiceRefId`**: Your original order ID, echoed back. Use this to match the response to your internal records.
* **`networkTransactionId`**: A unique ID assigned by the card network (Visa, Mastercard, etc.). This is crucial for disputes, [chargebacks](/docs/appendix/appendix-revolv3#chargeback), and reconciliation. **Always store this**. Learn more about [network transaction IDs](/docs/appendix/appendix-revolv3#network-transaction-id) in the glossary.
* **`invoiceStatus`**: The current status of the invoice. "Paid" means the payment was successful.
* **`invoiceAttemptStatus`**: The result of this specific payment attempt. "Success" means it went through.
* **`message`**: Human-readable result from the processor. "Approved" is what you want to see!
* **`amount`**: Confirms the currency and amount that was processed.
* **`paymentMethodId`**: If you want to charge this customer again later, you can use this ID instead of sending their full card details. This is called "[tokenization](/docs/appendix/appendix-revolv3#tokenization)" and is much more secure. Learn more in the [Payment Methods Guide](/docs/core-concepts/paymentmethod/paymentmethod-guide).
* **`paymentMethodTypeId`**: The type of payment method used:
  * `1` = Credit Card
  * `2` = ACH (bank transfer)
  * `3` = Google Pay
  * `4` = Apple Pay
* **`paymentProcessor`**: Which processor handled this transaction (useful for troubleshooting).
* **`paymentMethodCreditCardDetails`**:
  * **`binNumber`**: First 6 digits of the card (identifies the bank)
  * **`paymentLast4Digit`**: Last 4 digits (safe to display to customers)
  * **`paymentExpirationDate`**: When the card expires

> **Optional Field**: You can include `"includeRawProcessorResponse": false` in your request if you don't need the full processor response. By default, it's `true`.

## What to Do Next

After a successful payment:

1. **Store the important IDs**: Save `invoiceId`, `networkTransactionId`, and `merchantInvoiceRefId` in your database. You'll need these for:
   * Customer support ("I was charged twice!")
   * Refunds
   * Reconciliation (matching your records with bank statements)
   * Disputes and chargebacks
2. **Handle the response in your code**:
   * If `invoiceAttemptStatus` is "Success", show a confirmation page to the customer
   * If it's anything else, check the `message` field for the reason and handle accordingly
3. **Consider storing the payment method**: If the customer might buy again, save the `paymentMethodId` so they don't have to re-enter their card next time.
4. **Update your order status**: Mark the order as "paid" in your system and trigger any fulfillment processes (send confirmation email, ship the product, etc.).

## Handling Errors

If a payment fails, the `invoiceAttemptStatus` will be something other than "Success", and the `message` field will explain why. Common reasons include:

* Insufficient funds
* Card expired
* Incorrect billing address
* Card reported as stolen
* Bank declined (fraud prevention)

Always show a helpful error message to your customer and give them a chance to try a different payment method.

## Next Steps

Now that you've processed a payment, explore these related topics:

* [**Payment Methods Guide**](/docs/core-concepts/paymentmethod/paymentmethod-guide) — Learn how to store payment methods securely for future use
* [**Authorizations & Captures**](/docs/integration-flows/authorizations-captures) — Understand the two-step payment process (useful for hotels, pre-orders, etc.)
* [**Refunds**](/docs/integration-flows/refunds) — Learn how to issue refunds when customers return items
* [**Subscriptions**](/docs/core-concepts/subscription/create-subscription) — Set up recurring billing for subscription services

***