Advanced Integration
CollectCheckout.redirectToCheckout(options)
The "redirectToCheckout" function requires an object be passed with all the configuration options you are going to use.
Configuration Options
Variable | Type | Required? | Example |
lineItems | Array of objects | Yes |
|
lineItems.lineItemType | String ("purchase" or "customPayment") | No, defaults to "purchase" | |
lineItems.sku | String | Yes, when lineItemType is purchase | |
lineItems.quantity | Number | Yes, when lineItemType is purchase | |
lineItems.description | String | Yes, when lineItemType is customPayment | |
lineItems.currency | String | Yes, when lineItemType is customPayment | |
type | String ("sale", "auth", or "customerVaultOnly") | No, defaults to "sale" |
|
collectShippingInfo | Bool | No, defaults to false |
|
customerVault | Object | No |
|
customerVault.addCustomer | Bool | No, defaults to false | |
successUrl | String | No |
|
cancelUrl | String | No |
|
receipt | Object | No, defaults to no receipt |
|
receipt.showReceipt | Bool | No, defaults to false | |
receipt.redirectToSuccessUrl | Bool | No, defaults to false | |
receipt.sendToCustomer | Bool | No, defaults to false |
Line Items
All line items in a button configuration must already exist in the Product Manager in your merchant account. redirectToCheckout
will throw an error if you try to pass in SKUs that do not exist. In addition, you can not create a checkout page with products of differing currencies.
"Custom Payment" Line Items
If you'd like to allow the customer to pay a custom amount for an item, pass in a special line item that enables the customer to specify how much they are paying for an item. Often this will be used with a single item so the customer can make a donation of their chosen amount, but it could be used for anything where you'd like to give the customer the ability to pay what they want for something.
For example, this could be done in lineItems
as such:
lineItems: {
lineItemType: "customPayment",
description: "Custom Payment Amount",
currency: "USD"
}
This would let the customer specify the price for "Custom Payment Amount" on the Checkout cart page. You can also include fixed-price line items as well, but there can only be one "customPayment" item per cart configuration.
Transaction Type
Collect Checkout defaults to processing sale transactions, but you can perform an auth-only transaction instead by passing in the type
variable with value "auth". Auth-only transactions will immediately authorize the customer's card, but you will need to capture that transaction outside of Collect Checkout to receive funding.
Alternatively, if you would just like to save a customer to the Customer Vault without running a sale or auth, then you may pass in the value "customerVaultOnly". In this case, also send in the customerVault
object with the action you are performing in the Vault.
Shipping Information
By default, Collect Checkout will not ask the customer to enter their shipping information. If you need this, it can be collected by passing in the collectShippingInfo
variable.
Customer Vault
If you would like to save the customer's payment information in the Customer Vault, then you can provide the customerVault
object to request it be added upon a successful transaction. A random ID will be assigned to the new Vault ID, and you can receive that value in the successURL as documented below.
Success URL
This is the URL the customer will be redirected to after completing an approved transaction. This URL must be on the allowlist in your merchant control panel and you can use this value to retrieve the transaction ID and vault ID.
By adding (TRANSACTION_ID)in the string, you will receive the gateway transaction ID in its place in the redirect. For example, a successUrl of: https://example.com/receipt?id=(TRANSACTION_ID) will redirect to: https://example.com/receipt?id=3453356345
In this case, the transaction ID is 3453356345, which you can use to query on the full transaction details.
If adding to the Vault, you may also include (CUSTOMER_VAULT_ID) to receive the customer's Vault ID.
Variable | Description |
---|---|
(TRANSACTION_ID) | The transaction Id for the transaction that was processed |
(CUSTOMER_VAULT_ID) | The Customer Vault ID |
![](https://go.nmi.com/l/153691/2023-11-30/4fs71x/153691/1701364621blZe0v5A/RKI.png)
Cancel URL
This is the URL the customer will be redirected to if they decide to cancel out of the checkout page. This is done from a "close" button displayed in the Collect Checkout page. Unlike the Success URL, there are not variables that can be passed here since the customer will not have completed a transaction in this case.
Receipts
By default, Collect Checkout assumes the integrator will display a receipt to the customer, but if you would like Collect Checkout to display a basic receipt to the user, that can be done with the receipt
object.
"showReceipt" determines whether a receipt is shown on the checkout page. "redirectToSuccessUrl" determines whether that receipt shows a button for the customer to proceed to the success URL.
![](https://go.nmi.com/l/153691/2023-11-30/4fs71x/153691/1701364621blZe0v5A/RKI.png)
"sendToCustomer" allows you to have an email be sent from the gateway to the customer upon a successful transaction. There will be no email sent by default, but passing this as "true" inside the receipt
object will send an email receipt to the customer after an approved sale or authorization.
Updated about 1 month ago