Skip to main content

​
What is a Payment Method and Why Store It?

A Payment Method in Revolv3 is a securely stored reference to a customer’s payment credential (like a credit card or bank account). Instead of asking customers to enter their card details every time they make a purchase, you can store their payment information once and reuse it. Why is this useful?
  • Better customer experience: Customers don’t have to re-enter their card details every time
  • Faster checkout: One-click purchases for returning customers
  • Security: You never store full card numbers in your database (more on this below)
  • Recurring billing: Essential for subscriptions and recurring payments

​
Understanding Tokenization

When you store a payment method, Revolv3 uses a process called tokenization. Here’s how it works:
  1. You send the full card details to Revolv3 (card number, expiration, CVV)
  2. Revolv3 securely stores the card information in a PCI-compliant vault
  3. Revolv3 returns a token (called a paymentMethodId) that represents the card
  4. You store only the token in your database - never the actual card number
Security benefits:
  • Your database never contains sensitive card data, reducing your security risk
  • If your database is compromised, attackers only get tokens (which are useless without Revolv3)
  • You don’t need to be PCI-compliant for storing tokens (Revolv3 handles that)
  • Card details are encrypted and stored in secure, compliant systems

​
Two Ways to Create Payment Methods

You have two options for creating payment methods:
  1. Create a Payment Method separately before processing a payment (useful if you want to verify the card first or collect payment info ahead of time)
  2. Automatically create one when processing a payment (Revolv3 will create and return a paymentMethodId in the response)
Both approaches work the same way - the difference is timing. Let’s look at both.

​
Creating a Payment Method

If you want to create a payment method before processing a payment (for example, to verify the card or set up a subscription), you can create it separately.

​
API Endpoint

POST {{Api Root}}/api/PaymentMethod

​
Sample API Request

{
  "BillingAddress": {
    "AddressLine1": "100 Main Street",
    "AddressLine2": "",
    "City": "Santa Ana",
    "State": "CA",
    "PostalCode": "90000",
    "Country": "US"
  },
  "BillingFullName": "John Smith",
  "CreditCard": {
    "PaymentAccountNumber": "4111111111111111",
    "ExpirationDate": "1025", // Format: MMYY (October 2025)
    "SecurityCode": 123 // CVV/CVC code
  },
  "MerchantPaymentMethodRefId": "payment-method-ref-id_hgays-213-4rf4" // Your internal reference
}

​
Understanding the Request Fields

FieldDescription
BillingAddressThe address associated with the credit card. This is used for fraud prevention - banks verify that the address matches what they have on file.
AddressLine1, AddressLine2, City, State, PostalCode, CountryComplete billing address details. AddressLine2 is optional.
BillingFullNameThe name on the credit card. Can be a person’s name (like “John Smith”) or a company name. Use standard ASCII characters only (letters, numbers, spaces, hyphens) to avoid compatibility issues.
CreditCard.PaymentAccountNumberThe full credit card number (16 digits for most cards). Never store this in your database after getting the token.
CreditCard.ExpirationDateCard expiration date in MMYY format (e.g., “1025” means October 2025).
CreditCard.SecurityCodeThe CVV/CVC security code (usually 3-4 digits on the back of the card). Never store this - it’s only needed for the initial tokenization.
MerchantPaymentMethodRefIdYour own internal reference ID for tracking this payment method. Useful for matching Revolv3’s response back to your system.
Security Best Practice: Once you receive the paymentMethodId in the response, delete the full card number and CVV from your application’s memory. You’ll never need them again - just use the token.

​
Response When Creating a Payment Method

When you successfully create a payment method, Revolv3 returns a paymentMethodId that you can use for all future transactions with this customer. 
{
    "paymentMethodId": 16336, // This is what you'll use for future charges
    "billingAddressId": 17683,
    "billingAddress": {
        "addressId": 17683,
        "addressLine1": "100 Main Street",
        "addressLine2": "",
        "city": "Santa Ana",
        "state": "CA",
        "postalCode": "90000",
        "phoneNumber": null,
        "email": null,
        "country": "US"
    },
    "billingFirstName": "John",
    "billingLastName": "Smith",
    "merchantPaymentMethodRefId": "payment-method-ref-id_hgays-213-4rf4",
    "paymentMethodAchDetails": null,
    "paymentMethodCreditCardDetails": {
        "binNumber": "411111", // First 6 digits (identifies the bank)
        "paymentLast4Digit": "1111", // Last 4 digits (safe to display)
        "paymentExpirationDate": "1025"
    }
}

​
Understanding the Response

FieldDescription
paymentMethodIdThe most important field - this is your token. Store this in your database and use it for all future charges.
billingAddressIdRevolv3’s ID for the billing address (useful if you need to update it later).
billingAddressThe full billing address you provided, stored in Revolv3’s system.
merchantPaymentMethodRefIdYour original reference ID, echoed back for your records.
paymentMethodCreditCardDetails.binNumberThe first 6 digits of the card (Bank Identification Number). This identifies which bank issued the card.
paymentMethodCreditCardDetails.paymentLast4DigitThe last 4 digits of the card. This is safe to display to customers (e.g., “Your card ending in 1111”).
paymentMethodCreditCardDetails.paymentExpirationDateThe card’s expiration date in MMYY format.
Note: Notice that the response doesn’t include the full card number or CVV. Revolv3 never returns sensitive data - only the token and safe-to-display information like the last 4 digits.

​
Reusing a Stored Payment Method

Once you have a paymentMethodId, you can use it to charge the customer without ever handling their card details again. This is much more secure and provides a better user experience.

​
API Endpoint

POST {{Api Root}}/api/Payments/sale/{paymentMethodId}
Replace {paymentMethodId} with the ID you received when creating the payment method (e.g., 16336).

​
Sample API Request

{
    "NetworkProcessing": {
        "processingType": "initialRecurring", // Options: initialRecurring, initialInstallment, installment, recurring
        "originalNetworkTransactionId": null
    },
    "CustomerId": null, // Optional: link this payment to a customer record
    "Invoice": {
        "MerchantInvoiceRefId": "ABC309500654810", // Your order ID
        "Amount": {
            "value": 1.03 // Amount to charge
        }
    }
}

​
Understanding the Request Fields

FieldDescription
NetworkProcessing.processingTypeHow to classify this transaction. For a one-time purchase, use null. For subscriptions, use initialRecurring for the first payment, then recurring for subsequent payments.
NetworkProcessing.originalNetworkTransactionIdLeave null for new transactions. Use this if you’re referencing a previous transaction (like a follow-up payment).
CustomerIdOptional. If you have a customer record in Revolv3, link this payment to it. Otherwise, leave null.
Invoice.MerchantInvoiceRefIdYour internal order or invoice ID. Use this to match the response back to your system.
Invoice.Amount.valueThe amount to charge (USD is a default).

​
Payment Response

When you successfully charge a stored payment method, you’ll get a response similar to when you charge a card directly: 
{
    "customerId": null,
    "invoiceId": 575950,
    "merchantInvoiceRefId": "ABC309500654810",
    "merchantPaymentMethodRefId": null,
    "networkTransactionId": "295845970297960",
    "invoiceStatus": "Paid",
    "invoiceAttemptStatus": "Success",
    "message": "Approved",
    "amount": {
        "currency": "USD",
        "value": 1.03
    },
    "paymentMethodId": 63121, // The payment method that was charged
    "paymentMethodTypeId": 1, // 1=Credit Card, 2=ACH, 3=GooglePay, 4=ApplePay
    "paymentProcessor": "WorldPay",
    "processorMerchantId": "10071676",
    "rawResponse": null,
    "paymentMethodCreditCardDetails": {
        "binNumber": "411111",
        "paymentLast4Digit": "1111",
        "paymentExpirationDate": "1130",
        "accountUpdateMessage": null,
        "accountUpdateDateTime": null
    },
    "responseMessage": "Approved",
    "responseCode": "000"
}

​
Understanding the Response

FieldDescription
invoiceIdRevolv3’s unique identifier for this invoice. Save this for refunds and customer support.
merchantInvoiceRefIdYour original order ID, echoed back.
networkTransactionIdThe transaction ID from the card network. Always store this - you’ll need it for disputes, chargebacks, and reconciliation.
invoiceStatusCurrent status of the invoice. “Paid” means the payment succeeded.
invoiceAttemptStatusResult of this payment attempt. “Success” means it went through.
messageHuman-readable result.
paymentMethodIdConfirms which stored payment method was used.
paymentMethodTypeIdType of payment method: 1 = Credit Card, 2 = ACH, 3 = Google Pay, 4 = Apple Pay

​
Account Updater: Keeping Cards Current

Some payment processors support Account Updater, a service that automatically updates expired or replaced cards in your stored payment methods. For example, if a customer gets a new card number or their card expires, Account Updater can update your records so recurring payments don’t fail. When Account Updater updates a card, you’ll see additional fields in the response: 
{
    "paymentMethodCreditCardDetails": {
        "binNumber": "411111",
        "paymentLast4Digit": "1111",
        "paymentExpirationDate": "1130",
        "accountUpdateMessage": "NEW_EXPIRY", // Indicates what was updated
        "accountUpdateDateTime": "2025-10-30T11:46:33" // When it was updated
    }
}
This happens automatically - you don’t need to do anything. Revolv3 handles it behind the scenes to keep your payment methods current and reduce failed payments.

​
Real-World Use Cases

E-commerce with saved cards: When a customer checks out, offer to “save this card for faster checkout.” Store the paymentMethodId and show “Pay with card ending in 1111” on their next visit. Subscription services: When a customer signs up for a monthly subscription, create a payment method and use it for all recurring charges. Account Updater will keep the card current even if it expires. One-click purchases: Store payment methods for returning customers so they can complete purchases with a single click instead of entering card details every time. Guest checkout with optional save: Allow customers to checkout as guests, but offer to save their payment method if they create an account later.

​
Summary

ActionAPI EndpointPurpose
Create a Payment MethodPOST /api/PaymentMethodSecurely store a customer’s payment credential and get a token (paymentMethodId)
Charge a Stored Payment MethodPOST /api/Payments/sale/{paymentMethodId}Charge a customer using a stored payment method without handling card details

​
Security Reminders

  • Do: Store paymentMethodId tokens in your database
  • Do: Display the last 4 digits to customers for confirmation
  • Do: Delete card numbers and CVV codes from memory after tokenization
  • Don’t: Store full card numbers or CVV codes in your database
  • Don’t: Log card numbers or CVV codes
  • Don’t: Send card details in URLs or query parameters

​
Next Steps