Skip to main content
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 credit 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 Obtain API Keys and Static Token Authentication (x-revolv3-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 credit 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: 
{
  "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
    }
  }
}

​
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: 
{
    "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"
}

​
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, and reconciliation. Always store this. Learn more about network transaction IDs 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” and is much more secure. Learn more in the Payment Methods 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 — Learn how to store payment methods securely for future use
  • Authorizations & Captures — Understand the two-step payment process (useful for hotels, pre-orders, etc.)
  • Refunds — Learn how to issue refunds when customers return items
  • Subscriptions — Set up recurring billing for subscription services