CellPoint's Velocity API lets a customer split their payment between multiple available payment methods. The customer may split payments for a single transaction or for a payment session with multiple transactions. The merchant configures the business rules for this process.

Workflow

The workflow for split payments is as follows:

Initialize request - The customer clicks the payment button, prompting the merchant's front-end application to send an Initialize request for the full transaction amount to the Velocity API.
Initialize response - The API checks available payment options. It sends an Initialize response to the merchant that includes the session ID, the transaction ID, and all applicable payment combinations.
Payment method selection - The front-end application displays payment options to the customer, including the option of a split payment. The customer selects to split their payment, selects their first payment method, and enters the amount to apply to that payment method.
Proceed with split payment amount - Depending on the selected payment method, the front-end application sends a Pay or Authorize request to the API for the amount assigned to that payment method.
Get transaction status - After each transaction, the front-end application sends a Get Transaction Status request to the API. The API returns the complete session status and any pending amount.
Subsequent Initialize - If the Get Transaction Status response shows a pending amount, the front-end application sends another Initialize request that includes the session ID and the pending amount.
Repeat as necessary - The front-end application presents the pending amount and available payment options to the customer, who selects their next payment method and amount. Using the same session ID, the front-end application sends a Pay and/or Authorize request for the next payment method and amount, and then a Get Transaction Status request. If the API again returns a pending amount, the front-end application repeats steps 6 and 7 until the Get Transaction Status response shows no pending amount.

Expand this section for a diagram of the split payments workflow.

Prerequisite

Work with your CellPoint Digital sales representative or account manager to sign up, set up your test account, and access your testing credentials.

Integration

Complete the following steps to use split payments with your integration.

1. Initialize payment

Endpoint: /mpoint/initialize-payment
Method: POST

Once the page has loaded, send a POST request to the /mpoint/initialize-payment endpoint of the CellPoint Velocity API for the full transaction amount. For more information, see the API integration guide and our Initialize API reference.

If split payments are available, the API returns a first Initialize response that contains the following:

A transaction ID (in the transaction attribute id)
A session ID (in the session attribute id)
A <split_payment> element describing available payment combinations

See the sample code below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
		<name>Test</name>
		<callback-url>[callback url]</callback-url>
		<accept-url/>
	</client-config>
	<transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
		<amount country-id="[integer]" currency="USD" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
		<mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
		<callback-url>[CALLBACK URL]</callback-url>
		<accept-url/>
	</transaction>
	<session id="[integer]" total-amount="10025" type="1">
		<amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="USD" currency-id="840" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
		<status>4001</status>
	</session>
	<split_payment>
		<configuration>
			<applicable_combinations>
				<combination>
					<payment_type>
						<id>1</id>
						<sequence>1</sequence>
					</payment_type>
					<payment_type>
						<id>2</id>
						<sequence>2</sequence>
					</payment_type>
					<is_one_step_authorization>true</is_one_step_authorization>
				</combination>
				<combination>
					<payment_type>
						<id>1</id>
						<sequence>1</sequence>
					</payment_type>
					<payment_type>
						<id>1</id>
						<sequence>2</sequence>
					</payment_type>
					<is_one_step_authorization>false</is_one_step_authorization>
				</combination>
			</applicable_combinations>
		</configuration>
	</split_payment>
	<cards>
		<card cvc-length="3" cvcmandatory="false" dcc="false" enabled="true" id="8" instalment="0" max-length="19" min-length="13" payment-type="1" preferred="false" processor-type="1" psp-id="21" state-id="1" type-id="8">
			<name>Visa</name>
			<prefixes>
				<prefix>
					<min>4000</min>
					<max>4999</max>
				</prefix>
				<prefix>
					<min>413222</min>
					<max>413222</max>
				</prefix>
			</prefixes>Visa
		</card>
		<card cvc-length="-1" cvcmandatory="false" dcc="true" enabled="true" id="28" installment="0" max-length="-1" min-length="-1" payment-type="4" preferred="false" presentment-currency="false" processor-type="4" psp-id="24" state-id="1" type-id="28">
			<name>[PSP]</name>
			<prefixes>
				<prefix>
					<min>0</min>
					<max>0</max>
				</prefix>
			</prefixes>[PSP name]
		</card>
	</cards>
	<vouchers>
		<card cvc-length="-1" cvcmandatory="false" dcc="false" enabled="true" id="26" installment="0" max-length="-1" min-length="-1" payment-type="2" preferred="false" presentment-currency="false" processor-type="2" psp-id="-1" state-id="1" type-id="26">
			<name>TravelFund</name>
			<prefixes>
				<prefix id="337">
					<min>-1</min>
					<max>-1</max>
				</prefix>
			</prefixes>TravelFund
		</card>
	</vouchers>
</root>

📘
Note: In the case of a split abandoned payment, the Initialize response returns session with an amount value equal to its total-amount.
A split abandoned payment happens when a customer starts a fresh transaction and leaves a current split payment.

For a description of response parameters, see Initialize Response Parameters in our API reference.

2. Offer payment options

Use the data from the first Initialize response to present payment options to the customer. Let the customer select or enter the following:

The choice to split their payment between multiple payment methods.
The first payment method they wish to use. Let them do so by either entering payment information or selecting a stored method of payment (if applicable).
The amount to apply to that first payment method.

3. Proceed with payment

When the customer selects their payment method and assigns an amount to it, send a Pay or Authorize request. The type of request depends on the type of payment method:

APM - If the payment method is an alternate payment method (APM), send a Pay request (step 3a) and then an Authorize request (step 3b).
Card, voucher, or points/miles - If the payment method is a card, voucher, or points/miles, just send an Authorize request (skip to step 3b).

3a. Pay request

Endpoint: /mpoint/pay
Method: POST

If the payment method is an APM, send a Pay request that includes the following:

Information about the payment method
The amount applied to that payment method
The session ID returned in the Initialize response

For more information on sending a Pay request, see the API integration guide and our Pay API reference.

3b. Authorize request

Endpoint: /mpoint/authorize-payment
Method: POST

If the payment method is a card, voucher, or points/miles, or if you sent a Pay request and received a success response, send an Authorize request that includes the following:

Information about the payment method
The amount applied to that payment method
The session ID returned in the Initialize response

For more information on sending an Authorize request, see the API integration guide and our Authorize API reference.

4. Get transaction status

Endpoint: /mpoint/get-transaction-status
Method: GET

Send a Get Transaction Status request that includes the session ID returned in the Initialize response. The API returns a Get Transaction Status response with the session status of this split payment session.

If the Get Transaction Status response has a session: amount value of 0, the full amount has been paid and the process is complete. If the Get Transaction Status response has a nonzero value in session: amount, proceed to step 5.

For more information on sending a Get Transaction Status request, see the API integration guide and our Get Transaction Status API reference.

5. Initialize second payment

Endpoint: /mpoint/initialize-payment
Method: POST

If the Get Transaction Status response has a nonzero value in session: amount, that value is a pending transaction amount that must be applied to other payment method(s).

In this case, send another Initialize request. Include the session ID and the pending amount (the remaining transaction amount) in the request.

See sample code for a subsequent Initialize response below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<client-config account="[integer]" auto-capture="false" id="[integer]" mode="[integer]" store-card="[integer]">
		<name>Test</name>
		<callback-url>[callback url]</callback-url>
		<accept-url/>
	</client-config>
	<transaction auto-capture="true" eua-id="[integer]" id="[integer]" language="en" mode="1" order-no="" type-id="[integer]">
		<amount country-id="[integer]" currency="USD" format="{CURRENCY}{PRICE}" symbol="$">10025</amount>
		<mobile country-id="[integer]" operator-id="[integer]">30206172</mobile>
		<callback-url>[CALLBACK URL]</callback-url>
		<accept-url/>
	</transaction>
	<session id="[integer]" total-amount="10025" type="1">
		<amount alpha2code="US" alpha3code="USA" code="840" country-id="200" currency="USD" currency-id="840" format="{CURRENCY}{PRICE}" symbol="$">5000</amount>
		<status>4031</status>
	</session>
	<split_payment>
		<active_split>
			<current_split_sequence>2</current_split_sequence>
			<transactions>
				<transaction>
					<payment_type>1</payment_type>
					<id>5297575</id>
					<sequence>1</sequence>
				</transaction>
			</transactions>
		</active_split>
		<configuration>
			<applicable_combinations>
				<combination>
					<payment_type>
						<id>1</id>
						<sequence>1</sequence>
					</payment_type>
					<payment_type>
						<id>2</id>
						<sequence>2</sequence>
					</payment_type>
					<is_one_step_authorization>true</is_one_step_authorization>
				</combination>
				<combination>
					<payment_type>
						<id>1</id>
						<sequence>1</sequence>
					</payment_type>
					<payment_type>
						<id>1</id>
						<sequence>2</sequence>
					</payment_type>
					<is_one_step_authorization>false</is_one_step_authorization>
				</combination>
			</applicable_combinations>
		</configuration>
	</split_payment>
	<cards>
		<card cvc-length="3" cvcmandatory="false" dcc="false" enabled="true" id="8" instalment="0" max-length="19" min-length="13" payment-type="1" preferred="false" processor-type="1" psp-id="21" state-id="1" type-id="8">
			<name>Visa</name>
			<prefixes>
				<prefix>
					<min>4000</min>
					<max>4999</max>
				</prefix>
				<prefix>
					<min>413222</min>
					<max>413222</max>
				</prefix>
			</prefixes>Visa</card>
		<card cvc-length="-1" cvcmandatory="false" dcc="true" enabled="true" id="28" installment="0" max-length="-1" min-length="-1" payment-type="4" preferred="false" presentment-currency="false" processor-type="4" psp-id="24" state-id="1" type-id="28">
			<name>[PSP]</name>
			<prefixes>
				<prefix>
					<min>0</min>
					<max>0</max>
				</prefix>
			</prefixes>[PSP name]
		</card>
	</cards>
	<vouchers>
		<card cvc-length="-1" cvcmandatory="false" dcc="false" enabled="true" id="26" installment="0" max-length="-1" min-length="-1" payment-type="2" preferred="false" presentment-currency="false" processor-type="2" psp-id="-1" state-id="1" type-id="26">
			<name>TravelFund</name>
			<prefixes>
				<prefix id="337">
					<min>-1</min>
					<max>-1</max>
				</prefix>
			</prefixes>TravelFund
		</card>
	</vouchers>
</root>

For a description of response parameters, see Initialize Response Parameters in our API reference.

6. Repeat as necessary

Use information in the subsequent Initialize response to present the customer with the pending amount and available payment methods, and let the customer select the next payment method and assign an amount to it. Use this information to send a Pay request (if applicable), an Authorize request, and then a Get Transaction Status request. Repeat steps 5 and 6 until the Get Transaction Status response has a value of 0 in session: amount.