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 - 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.
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 rules -
Optional
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.