> ## 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.
# Create a Payment Method
> Learn how to securely store customer payment methods using tokenization, and reuse them for future transactions without handling sensitive card data.
## 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
```json theme={null}
{
"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
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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**](/docs/core-concepts/paymentmethod/ach-direct-debit) — Learn how to store and charge bank accounts
* [**Subscriptions**](/docs/core-concepts/subscription/create-subscription) — Use payment methods for recurring billing
* [**Account Updater**](/docs/core-concepts/paymentmethod/account-updater) — Understand how cards are automatically updated
***