Create a Payment Method

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:

You send the full card details to Revolv3 (card number, expiration, CVV)
Revolv3 securely stores the card information in a PCI-compliant vault
Revolv3 returns a token (called a paymentMethodId) that represents the card
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:

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)
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",
    "SecurityCode": 123
  },
  "MerchantPaymentMethodRefId": "payment-method-ref-id_hgays-213-4rf4"
}

In this example, ExpirationDate uses MMYY format (e.g., 1025 means October 2025), SecurityCode is the CVV/CVC, and MerchantPaymentMethodRefId is your own internal reference ID.

Understanding the Request Fields

Field	Description
`BillingAddress`	The 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, Country`	Complete billing address details. AddressLine2 is optional.
`BillingFullName`	The 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.PaymentAccountNumber`	The full credit card number (16 digits for most cards). Never store this in your database after getting the token.
`CreditCard.ExpirationDate`	Card expiration date in MMYY format (e.g., “1025” means October 2025).
`CreditCard.SecurityCode`	The 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.
`MerchantPaymentMethodRefId`	Your 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,
    "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",
        "PaymentLast4Digit": "1111",
        "PaymentExpirationDate": "1025"
    }
}

Here, paymentMethodId is the token you’ll use for future charges, binNumber is the first 6 digits of the card (bank identifier), and paymentLast4Digit is safe to display to customers.

Understanding the Response

Field	Description
`paymentMethodId`	The most important field - this is your token. Store this in your database and use it for all future charges.
`billingAddressId`	Revolv3’s ID for the billing address (useful if you need to update it later).
`billingAddress`	The full billing address you provided, stored in Revolv3’s system.
`merchantPaymentMethodRefId`	Your original reference ID, echoed back for your records.
`paymentMethodCreditCardDetails.binNumber`	The first 6 digits of the card (Bank Identification Number). This identifies which bank issued the card.
`paymentMethodCreditCardDetails.paymentLast4Digit`	The last 4 digits of the card. This is safe to display to customers (e.g., “Your card ending in 1111”).
`paymentMethodCreditCardDetails.paymentExpirationDate`	The 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",
    "OriginalNetworkTransactionId": null
  },
  "CustomerId": null,
  "Invoice": {
    "MerchantInvoiceRefId": "ABC309500654810",
    "Amount": {
      "Value": 1.03
    }
  }
}

In this request, processingType controls how networks classify the transaction (recurring vs installment), CustomerId can link to an existing customer record, MerchantInvoiceRefId is your order ID, and Amount.value is the charge amount.

Understanding the Request Fields

Field	Description
`NetworkProcessing.processingType`	How 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.originalNetworkTransactionId`	Leave `null` for new transactions. Use this if you’re referencing a previous transaction (like a follow-up payment).
`CustomerId`	Optional. If you have a customer record in Revolv3, link this payment to it. Otherwise, leave `null`.
`Invoice.MerchantInvoiceRefId`	Your internal order or invoice ID. Use this to match the response back to your system.
`Invoice.Amount.value`	The 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,
  "PaymentMethodTypeId": 1,
  "PaymentProcessor": "WorldPay",
  "ProcessorMerchantId": "10071676",
  "RawResponse": null,
  "PaymentMethodCreditCardDetails": {
    "BinNumber": "411111",
    "PaymentLast4Digit": "1111",
    "PaymentExpirationDate": "1130",
    "AccountUpdateMessage": null,
    "AccountUpdateDateTime": null
  },
  "ResponseMessage": "Approved",
  "ResponseCode": "000"
}

In this response, paymentMethodId confirms which stored payment method was used, and paymentMethodTypeId indicates the type (1 = credit card, 2 = ACH, 3 = Google Pay, 4 = Apple Pay).

Understanding the Response

Field	Description
`invoiceId`	Revolv3’s unique identifier for this invoice. Save this for refunds and customer support.
`merchantInvoiceRefId`	Your original order ID, echoed back.
`networkTransactionId`	The transaction ID from the card network. Always store this - you’ll need it for disputes, chargebacks, and reconciliation.
`invoiceStatus`	Current status of the invoice. “Paid” means the payment succeeded.
`invoiceAttemptStatus`	Result of this payment attempt. “Success” means it went through.
`message`	Human-readable result.
`paymentMethodId`	Confirms which stored payment method was used.
`paymentMethodTypeId`	Type 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",
    "AccountUpdateDateTime": "2025-10-30T11:46:33"
  }
}

Here, accountUpdateMessage indicates what the account updater changed (for example, a new expiry date), and accountUpdateDateTime records when it was updated.

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

Action	API Endpoint	Purpose
Create a Payment Method	`POST /api/PaymentMethod`	Securely store a customer’s payment credential and get a token (`paymentMethodId`)
Charge a Stored Payment Method	`POST /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

ACH Direct Debit — Learn how to store and charge bank accounts
Subscriptions — Use payment methods for recurring billing
Account Updater — Understand how cards are automatically updated

Getting Started

Authentication & Security

Core Concepts & Data Models

Integration Flows

Plugins

API Reference

Webhooks & Event Handling

Error Codes & Troubleshooting

Testing & Sandbox

Certification & Go-Live Checklist

Appendix / Glossary

FAQ

What is a Payment Method and Why Store It?

Understanding Tokenization

Two Ways to Create Payment Methods

Creating a Payment Method

API Endpoint

Sample API Request

Understanding the Request Fields

Response When Creating a Payment Method

Understanding the Response

Reusing a Stored Payment Method

API Endpoint

Sample API Request

Understanding the Request Fields

Payment Response

Understanding the Response

Account Updater: Keeping Cards Current

Real-World Use Cases

Summary

Security Reminders

Next Steps

​What is a Payment Method and Why Store It?

​Understanding Tokenization

​Two Ways to Create Payment Methods

​Creating a Payment Method

​API Endpoint

​Sample API Request

​Understanding the Request Fields

​Response When Creating a Payment Method

​Understanding the Response

​Reusing a Stored Payment Method

​API Endpoint

​Sample API Request

​Understanding the Request Fields

​Payment Response

​Understanding the Response

​Account Updater: Keeping Cards Current

​Real-World Use Cases

​Summary

​Security Reminders

​Next Steps

What is a Payment Method and Why Store It?

Understanding Tokenization

Two Ways to Create Payment Methods

Creating a Payment Method

API Endpoint

Sample API Request

Understanding the Request Fields

Response When Creating a Payment Method

Understanding the Response

Reusing a Stored Payment Method

API Endpoint

Sample API Request

Understanding the Request Fields

Payment Response

Understanding the Response

Account Updater: Keeping Cards Current

Real-World Use Cases

Summary

Security Reminders

Next Steps