Initiate a payment. The payment can be either one-time or it can include data to define the initial transaction in a recurring or installment stream. This allows the networks to tie subsequent transactions back to the original approval, ensuring a seamless and efficient payment process.
The required argument for this endpoint are payment method information and invoice.
Description of request parameters
- customerId
Optional
Unique identifier for the customer.
No validation rules- includeRawProcessorResponse
Optional. Default - false.
Determine whether to return raw processor data in the response.
No validation rules- invoice
Required
Invoice
No validation rules- merchantInvoiceRefId
Optional
Merchant's unique identifier for the invoice.
No validation rules- orderProcessingChannel
Optional
Specifies the sales channel through which the shopper provides their card details. Currently, the moto value can only be sent for WorldPay. For other processors, ecommerce is used by default.
Possible values:- ecommerce - Internet or electronic commerce transaction.
- moto - Single mail or telephone order transaction.
Validation rules:
- If the processor is WorldPay, both ecommerce and moto are allowed.
- amount
Required
The amount information for the payment.
No validation rules- currency
Optional. Default - USD.
The three-character ISO currency code (currently only USD is supported).
Validation rules:- Must be 3 characters in length
- value
Required
The amount information for the payment.
Validation rules:- Must NOT be less than zero
- dynamicDescriptor
- Optional
Allows the merchant to define a dynamic descriptor, which appears in the payment statement. For dynamic descriptor, special configuration is required. For more information, please contact Revolv3 Support Team.
Processors that support Dynamic Descriptor: Nuvei, WorldPay. - subMerchantId
Optional
The internal merchant’s ID, which is sent to the relevant card scheme.
Validation rules:- Nuvei processor: the maximum length is 15 characters.
- WorldPay processor: field is not supported.
- subMerchantName
Optional
The merchant name, as is displayed for the transaction on the consumer’s card statement. For payment facilitator only, might consist of the following structure: Prefix*-
where:
Prefix – The PayFac prefix, approved by processor.
* – A fixed character.
- – Sub-merchant name.Recommended! An alternative method to define a prefix is by configuring it through the Revolv3 Portal. For more information, please contact Revolv3 Support Team.
Validation rules:- Nuvei processor: the maximum length of the parameter is 22. Possible prefix length 3 or 5 or 7 or 12 characters.
- WorldPay processor: if the value is specified, it must be between 4 and 25 characters. Possible prefix length 3 or 7 or 12 characters. Field accepts numbers, letters and special characters as follows: ampersand, asterisk (zero or one), comma, dash, period, space, or pound sign.
- subMerchantPhone
Optional
The merchant (sub-merchant for payment facilitators) contact information, as is displayed for the transaction on the consumer’s card statement.
Validation rules:- Nuvei processor: the maximum length of the parameter is 13. It can also be an email address.
- WorldPay processor: the maximum length of the parameter is 13. Field accepts only numbers.
- countryCode
Optional
The payment facilitator’s sub-merchant’s 2-letter ISO country code.
Validation rules:- Nuvei processor: no validation rules.
- WorldPay processor: field is not supported.
- networkProcessing
Optional
Network processing information. Follow the link or contact Revolv3 support for more information.
No validation rules- processingType
Optional
Processing type is used to define the initial or subsequent transaction in a recurring or installment stream.
Validation rules:
If no value is supplied, a transaction is considered a one-time payment and will not be linked to the initial one.- Possible values: initialInstallment, initialRecurring, installment, recurring
- originalNetworkTransactionId
Optional
Element defines the networkTransactionId returned in the response messages for Visa, Mastercard, and Discover Auth/Sale transactions. You must include this element and the original value returned for subsequent (after the initial) Visa, Mastercard or Discover recurring/installment payments.
No validation rules- paymentMethod
Required
The payment method information for the payment. Only one payment method type should be provided with a transaction.
No validation rules
Supported payment methods: Credit card, ACH*, GooglePay*.
*Supported for specific processors.- billingAddress
Optional
The address associated with a payment method that is used for billing purposes. Either an Address ID or detailed address information can be provided.
No validation rules- addressId
Optional
The unique identifier of the address.
No validation rules- addressLine1
Optional
Address
Validation rules:- The length should be between 2 and 40 characters
- addressLine2
Optional
Supplemental information for the address.
Validation rules:- Maximum length 40 characters
- city
Optional
BillingAddress: City.
Validation rules:
DynamicDescriptor: The payment facilitator’s sub-merchant’s city name.- BillingAddress: The length should be no more than 25 characters
- DynamicDescriptor validation rules:
- Nuvei processor: maximum length of 20 characters.
- WorldPay processor: field is not supported.
- state
Optional
Two-letter state abbreviation
Validation rules:- Must be 2 characters in length
- postalCode
Optional
Postal code
Validation rules:- The length should be between 2 and 20 characters
- phoneNumber
Optional
The phone number associated with a payment method that is used for billing purposes.
No validation rulesOptional
The email associated with a billing address.
No validation rules- country
Optional
Country
Validation rules:- The input must be a valid Alpha2 code, Alpha3 code, UN code, or full country name
- billingFirstName
Required
The customers’s first name associated with a payment method that is used for billing purposes.
No validation rules- billingLastName
Required
The customers’s last name associated with a payment method that is used for billing purposes.
No validation rules- creditCard
Conditional. One payment method type is required.
Payment card information.
Validation rules:- Only one payment method type can be supplied
- paymentAccountNumber
- Conditional. The PAN is required if the credit card payment method type is supplied in the request.
Validation rules:
- The number must be a valid credit card number and will be verified using the Luhn algorithm.
- expirationDate
Conditional. The expiration date is required if the credit card payment method type is supplied in the request.
The card expiration date.
Validation rules:- Must be in one of the following formats: MMYY, MMYYYY, MM/YYY and MM/YYYYY
- securityCode
Optional
The card verification code. It is considered best practice to always include this value for card-not-present transactions. Failure to do so may lead to higher rates of declines, an increase in chargeback cases, and/or transaction downgrades.
Validation rules:- The length should be between 3 and 4 characters
- ach
Conditional. One payment method type is required.
ACH account information.
Validation rules:- Only one payment method type can be supplied
- routingNumber
Conditional. The routing number is required if the ACH payment method type is supplied in the request.
The 9-digit ACH routing number of the account.
Validation rules:- Must be 9 characters in length
- accountNumber
Conditional. The account number is required if the ACH payment method type is supplied in the request.
The US bank account number from which the payment will be debited.
Validation rules:- The length should be between 4 and 17 characters
- accountType
Conditional. The account type is required if the ACH payment method type is supplied in the request.
Bank account type.
Validation rules:- Possible values: Checking or Savings
- googlePay
Conditional. One payment method type is required.
GooglePay information.
Validation rules:- Only one payment method type can be supplied
- googlePayPaymentDataResponse
Conditional. The GooglePayPaymentDataResponse is required if the GooglePay payment method type is supplied in the request.
The data returned by Google Pay.
Validation rules:- Must contain the valid serialized JSON object
- merchantPaymentMethodRefId
Optional
Merchant's unique identifier for the payment method.
No validation rules
Description of response parameters
- rawResponse
- Conditional. The value is returned if includeRawProcessorResponse = true.
This field contains the raw data received from the processor after attempting to bill this payment. It does not contain any sensitive information. The field value is a string with the serialized response from the processor in JSON format.