> ## 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 Payment Method > Creates and stores a **new payment method** for a customer, such as a credit card, ACH account, or digital wallet token. This endpoint accepts full payment method details and securely tokenizes them for future use. It’s typically used during onboarding, checkout, or when a customer wants to add a new card or bank account to their profile. The created payment method can later be used for subscriptions, or one-time payments. ## OpenAPI ````yaml /api-reference/swagger.json post /api/PaymentMethod openapi: 3.0.4 info: title: Revolv3 OpenApi Spec description: Spec for Revolv3 version: 1.29.1 servers: - url: 'https://api-sandbox.revolv3.com ' security: [] paths: /api/PaymentMethod: post: tags: - PaymentMethod summary: Create Payment Method description: "Creates and stores a **new payment method** for a customer, such as a credit card, ACH account, or digital wallet token.\r\nThis endpoint accepts full payment method details and securely tokenizes them for future use.\r\n\r\nIt’s typically used during onboarding, checkout, or when a customer wants to add a new card or bank account to their profile.\r\nThe created payment method can later be used for subscriptions, or one-time payments." requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/CreatePaymentMethodRequestDTO' example: billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Santa Ana state: CA postalCode: '90000' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: payment-method-ref-id_hgays-213-4rf4 billingFirstName: John billingLastName: Smith billingFullName: null application/json: schema: $ref: '#/components/schemas/CreatePaymentMethodRequestDTO' example: billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Santa Ana state: CA postalCode: '90000' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: payment-method-ref-id_hgays-213-4rf4 billingFirstName: John billingLastName: Smith billingFullName: null text/json: schema: $ref: '#/components/schemas/CreatePaymentMethodRequestDTO' example: billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Santa Ana state: CA postalCode: '90000' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: payment-method-ref-id_hgays-213-4rf4 billingFirstName: John billingLastName: Smith billingFullName: null application/*+json: schema: $ref: '#/components/schemas/CreatePaymentMethodRequestDTO' example: billingAddress: addressId: null addressLine1: 100 Main Street addressLine2: null city: Santa Ana state: CA postalCode: '90000' phoneNumber: null email: null country: US creditCard: paymentAccountNumber: '4111111111111111' expirationDate: '1025' securityCode: null networkToken: null ach: null googlePay: null applePay: null merchantPaymentMethodRefId: payment-method-ref-id_hgays-213-4rf4 billingFirstName: John billingLastName: Smith billingFullName: null responses: '201': description: The payment method was successfully created content: text/plain: schema: $ref: '#/components/schemas/PaymentMethodDTO' example: paymentMethodId: 1 billingAddressId: 1 billingAddress: addressId: 1 addressLine1: 123 Main addressLine2: null 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' accountUpdateMessage: null accountUpdateDateTime: null accountUpdateCode: null application/json: schema: $ref: '#/components/schemas/PaymentMethodDTO' example: paymentMethodId: 1 billingAddressId: 1 billingAddress: addressId: 1 addressLine1: 123 Main addressLine2: null 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' accountUpdateMessage: null accountUpdateDateTime: null accountUpdateCode: null text/json: schema: $ref: '#/components/schemas/PaymentMethodDTO' example: paymentMethodId: 1 billingAddressId: 1 billingAddress: addressId: 1 addressLine1: 123 Main addressLine2: null 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' accountUpdateMessage: null accountUpdateDateTime: null accountUpdateCode: null '400': description: >- One or more fields in the request were not submitted or didn't pass validation. Please review the request body and parameters against the required schema. content: text/plain: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. application/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. text/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Unable to perform the request action with provided data. '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. application/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. text/json: schema: $ref: '#/components/schemas/StatusMessageResponse' example: message: Attempted to perform an unauthorized operation. security: - Bearer: [] components: schemas: CreatePaymentMethodRequestDTO: type: object properties: billingFirstName: maxLength: 100 minLength: 0 type: string description: "**Conditional**: either both BillingFirstName and BillingLastName or BillingFullName must be provided.\r\n\r\nThe customers’s first name associated with a payment method that is used for billing purposes." billingLastName: maxLength: 100 minLength: 0 type: string description: "**Conditional**: either both BillingFirstName and BillingLastName or BillingFullName must be provided.\r\n\r\nThe customers’s last name associated with a payment method that is used for billing purposes." billingFullName: maxLength: 200 minLength: 0 type: string description: "**Conditional**: either BillingFullName or both BillingFirstName and BillingLastName must be provided.\r\n\r\nThe customers’s full name associated with a payment method that is used for billing purposes. " billingAddress: allOf: - $ref: '#/components/schemas/CreateAddressRequestDTO' description: >- The address associated with a payment method that is used for billing purposes. Either an Address ID or detailed address information can be provided. creditCard: allOf: - $ref: '#/components/schemas/CreditCardDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nPayment card information." ach: allOf: - $ref: '#/components/schemas/AchDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nACH account information." googlePay: allOf: - $ref: '#/components/schemas/GooglePayDTO' description: "**Conditional**: one payment method type is required.\r\n\r\nGoogle Pay information." applePay: $ref: '#/components/schemas/ApplePayDto' merchantPaymentMethodRefId: maxLength: 100 type: string description: Merchant's unique identifier for the payment method. additionalProperties: false PaymentMethodDTO: type: object properties: paymentMethodId: maximum: 1000000000 minimum: 1 type: integer description: The unique identifier for the payment method information. format: int64 billingAddressId: maximum: 1000000000 minimum: 1 type: integer description: The unique identifier of the address. format: int64 billingAddress: $ref: '#/components/schemas/AddressDTO' billingFirstName: maxLength: 100 minLength: 0 type: string nullable: true billingLastName: maxLength: 100 minLength: 0 type: string nullable: true merchantPaymentMethodRefId: maxLength: 100 minLength: 0 type: string description: Merchant's unique identifier for the payment method. paymentMethodAchDetails: allOf: - $ref: '#/components/schemas/AchViewDTO' description: ACH account information. paymentMethodCreditCardDetails: allOf: - $ref: '#/components/schemas/CreditCardViewDTO' description: The details of credit card payment method. additionalProperties: false StatusMessageResponse: type: object properties: message: type: string nullable: true errors: type: array items: type: string nullable: true fluentValidatorErrors: type: array items: $ref: '#/components/schemas/ValidationFailure' nullable: true additionalProperties: false CreateAddressRequestDTO: type: object properties: addressLine1: maxLength: 3000 minLength: 0 type: string description: Address. nullable: true addressLine2: maxLength: 3000 minLength: 0 type: string description: Supplemental information for the address. city: maxLength: 3000 minLength: 0 type: string description: City. nullable: true state: maxLength: 2 minLength: 0 type: string description: State. nullable: true postalCode: maxLength: 20 minLength: 2 type: string description: Postal Code. nullable: true phoneNumber: maxLength: 20 minLength: 7 pattern: ^(?=.*\d)\+?[0-9\s\-\(\)\.]{7,20}$ type: string description: >- The phone number associated with a payment method that is used for billing purposes. email: maxLength: 3000 minLength: 0 type: string description: The email associated with a billing address. format: email country: maxLength: 2 minLength: 0 type: string description: >- The input must be a valid Alpha2 code, Alpha3 code, UN code, or full country name. addressId: maximum: 1000000000 minimum: 1 type: integer description: The unique identifier of the address. format: int64 additionalProperties: false CreditCardDTO: type: object properties: paymentAccountNumber: maxLength: 19 minLength: 8 type: string description: "**Conditional**: the PAN is required if the credit card payment method type is supplied in the request.\r\nThe number must be a valid credit card number and will be verified using the Luhn algorithm. Minimum length of 8 characters. Maximum length of 25 characters.\r\n\r\nPayment Account Number (PAN)." expirationDate: maxLength: 7 minLength: 0 type: string description: "**Conditional**: the expiration date is required if the credit card payment method type is supplied in the request.\r\n\r\nThe card expiration date." format: MMYY, MM/YY, MMYYYY, or MM/YYYY securityCode: maxLength: 4 minLength: 3 type: string description: "The card verification code. It is considered best practice to always include this value for card-not-present transactions.\r\n\r\nFailure to do so may lead to higher rates of declines, an increase in chargeback cases, and/or transaction downgrades." networkToken: allOf: - $ref: '#/components/schemas/NetworkTokenDto' description: External Network Token information. additionalProperties: false AchDTO: required: - accountNumber - routingNumber type: object properties: routingNumber: maxLength: 9 minLength: 9 pattern: ^[0-9]{9}$ type: string description: "**Conditional**: the routing number is required if the ACH payment method type is supplied in the request.\r\n\r\nThe 9-digit ACH routing number of the account." accountNumber: maxLength: 17 minLength: 4 pattern: ^[0-9]{4,17}$ type: string description: "**Conditional**: the account number is required if the ACH payment method type is supplied in the request.\r\nThe length should be between 4 and 17 characters.\r\n\r\nThe US bank account number from which the payment will be debited." accountType: maxLength: 20 type: string description: "**Conditional**: the account type is required if the ACH payment method type is supplied in the request.\r\n\r\nBank account type. Allowed values: Checking, Savings. Case-insensitive." additionalProperties: false GooglePayDTO: type: object properties: googlePayPaymentDataResponse: type: string description: "**Conditional**: the GooglePayPaymentDataResponse is required if the Google Pay payment method type is supplied in the request.\r\nMust contain the valid serialized JSON object.\r\n\r\nThe data returned by Google Pay." additionalProperties: false ApplePayDto: type: object properties: applePayToken: type: string nullable: true additionalProperties: false AddressDTO: type: object properties: addressId: type: integer description: The unique identifier of the address. format: int64 addressLine1: maxLength: 40 minLength: 2 type: string description: Address. nullable: true addressLine2: maxLength: 40 minLength: 0 type: string description: Supplemental information for the address. city: maxLength: 25 minLength: 2 type: string description: City. nullable: true state: maxLength: 2 minLength: 2 type: string description: Two-letter state abbreviation. nullable: true postalCode: maxLength: 20 minLength: 2 type: string description: Postal Code. nullable: true phoneNumber: maxLength: 20 minLength: 0 type: string description: >- The phone number associated with a payment method that is used for billing purposes. email: maxLength: 100 minLength: 0 type: string description: The email associated with a billing address. format: email country: maxLength: 2 minLength: 2 type: string description: Country. nullable: true additionalProperties: false AchViewDTO: type: object properties: accountNumberLast4Digits: maxLength: 4 minLength: 4 pattern: ^\d{4}$ type: string description: Last 4 digits of the bank account. accountNumberLength: maximum: 17 minimum: 4 type: integer description: Bank account number length. format: int32 accountType: maxLength: 8 minLength: 0 pattern: ^(Checking|Savings)$ type: string description: "**Conditional**: the account type is required if the ACH payment method type is supplied in the request.\r\n\r\nBank account type. Allowed values: Checking, Savings. Case-insensitive." additionalProperties: false nullable: true CreditCardViewDTO: type: object properties: binNumber: maxLength: 6 minLength: 0 pattern: ^\d{1,6}$ type: string description: First 6 digits (BIN) of the card number. paymentLast4Digit: maxLength: 4 minLength: 4 pattern: ^\d{4}$ type: string description: Payment card last 4 digits. paymentExpirationDate: maxLength: 4 minLength: 0 type: string description: The card expiration date. format: MMYY nullable: true accountUpdateMessage: maxLength: 500 minLength: 0 type: string description: Account updater message, if available. accountUpdateDateTime: maxLength: 20 minLength: 0 type: string description: UTC date-time of the last account updater event. format: YYYY-MM-DDThh:mm:ss nullable: true accountUpdateCode: maxLength: 50 minLength: 0 type: string description: Processor response code of the last account updater event. additionalProperties: false nullable: true ValidationFailure: type: object properties: propertyName: type: string nullable: true errorMessage: type: string nullable: true attemptedValue: nullable: true customState: nullable: true severity: $ref: '#/components/schemas/Severity' errorCode: type: string nullable: true formattedMessagePlaceholderValues: type: object additionalProperties: nullable: true nullable: true additionalProperties: false NetworkTokenDto: type: object properties: token: maxLength: 19 type: string description: Network token issued by a card network for a card. cryptogram: maxLength: 40 type: string description: >- One-time digital “stamp” of payment. Needed for all CIT (customer-initiated transactions), and the cryptogram will have to be generated by the same TR-TSP that provisioned the token. electronicCommerceIndicator: maxLength: 2 type: string description: >- An online payment security label indicating whether additional protection (such as 3-D Secure) was applied. paymentAccountReference: maxLength: 100 type: string description: >- A permanent unique identifier of a payment account that a payment system assigns to a card and uses instead of a real PAN within network tokens. expirationDate: maxLength: 7 minLength: 0 type: string description: Expiration date of the network token. format: MMYY, MM/YY, MMYYYY, or MM/YYYY nullable: true additionalProperties: false Severity: enum: - Error - Warning - Info type: string securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````