Accepting card payments

Smart Router greatly reduces the complexity of handling online card payments.
Our web and mobile app APIs transparently handle security standards and payment optimization while giving you maximum freedom in your coding and presentation style.

Typical purchasing processes

One example of a typical payment process might involve an online shopping cart that holds the selection of goods the customer wants to buy. Once the customer has finalized the contents of the cart, they
click a button to check out the cart (ie, proceed with payment). Then, they enter and authenticate their payment details and confirm the order. A purchase like this is known as a Cardholder Initiated Transaction (CIT).

From this point on, the merchant is mostly responsible for fulfilling the order (ie, handling it through to delivery, possibly with returns afterwards). This will often be straightforward but issues can sometimes arise along the way (the customer might ask for a refund, products might become unavailable, etc). The merchant must interact with the customer further in these cases. However, even when there are no problems, the merchant should still email the customer with updates about receiving the order and dispatching the goods.

Another example of a payment process is a subscription where the customer makes renewal payments periodically. The initial purchase is essentially a CIT, as in the first example, but the merchant is responsible for taking payments on the renewals automatically when they are due. Payments like these are known as Merchant Initiated Transactions (MITs).

Smart Router provides a number of features to keep track of these processes, including:

• An Invoice object to represent the full details of the order, such as the final contents of the shopping cart, their cost and availability, the delivery address for the order, and possibly other information relevant to the purchase. This object also has data fields to track changes to the fulfillment status of the order when they occur.

• Tokens to represent the customer's card details.

• A Customer object to manage returning customers (or recurring payments from a customer) by storing their contact and payment details.

• A communication system that uses webhooks to relay updates about payment and other stages of fulfillment to any systems that might need to respond.

The section below describes these features in more detail and explains how they interact during the lifecycle of an order.

How ProcessOut manages an order

When the user checks out their shopping cart, your server receives an HTTP request from the app to start the payment. The request will include the details of the cart and, most importantly, the amount the customer will be charged.

Below is a sequence diagram that shows the transaction flow. The following sections explain the flow in detail.

1. Creating an invoice

Your server responds to the request by creating an Invoice object.
The Invoice is the main object that Smart Router uses to represent the full lifecycle of an order from initiation through to shipping. It contains all available details of the purchase, including:

• Types and quantities of items purchased
• Total and individual cost of items
• Details of the Customer who made the purchase
• Details of the payment method
• Payment and delivery details and current status

Each Invoice object has an unique id property string that you can use to identify it within the
API. This is particularly important for passing the invoice data between the client and server because the ID string is
much shorter than the full data and contains no meaningful information that an attacker could use.
For example, you can use the invoice ID to accept payment for the order without revealing its details.

The next step for a CIT is for the server to respond to the client by sending back a request for payment on the invoice. For an MIT, the server can simply capture the payment when necessary using stored card details.

📘

This step is explained with more detail and code samples in the page about creating an invoice.

2. Obtaining a payment source token

The client app or web page will now prompt the customer to supply a payment source for the purchase.
The Smart Router API can accept card details securely from a form in your web or mobile app. The API sends the details to the ProcessOut vault and returns a card token to your code. You can use this token to capture payment on an invoice directly but if you do so then the token cannot be reused for future purchases. An alternative approach is to use the card token to create a Customer token that stores the card details along with other information such as contact details. You can generate tokens from a Customer object to use for payment, but unlike the one-off card tokens, Customer tokens are reusable.

Once you have obtained a payment source token, you can use it to authorize and capture payment on the invoice.

📘

This step is explained with more detail and code samples in the pages about tokenizing a card in the browser, tokenizing a card in a mobile app, and saving a token to capture future payments.

3. Authorizing a payment

This stage confirms that the customer has enough money in their bank account to complete the payment and then reserves that money (ie, stops it from being used to pay for anything else). It is only when the payment is captured in a separate stage that the money is actually transferred. Note that you can capture a payment up to 7 days after authorization, which may be useful for fraud prevention or other checks. You can also request an automatic delayed capture for a payment at the time of authorization.

For CITs, your client-side code makes an API call to authorize the payment using the payment source token and the invoice ID it received from the server. You must perform this authorization step on the client to comply with legislation on Strong Customer Authentication (SCA).

For MITs, authorization is an optional step if you intend to take payment immediately afterwards but it is still necessary if you want to delay payment. By its nature, an MIT can only be authorized on the server side.

📘

This step is explained with more detail and code samples in the page about authorizing a payment.

4. Capturing a payment

The final step in activating a payment is to capture the payment on the invoice from the server side. For CITs, you can do this after the card has been authorized on the client side. For MITs, you can capture payment with a stored Customer immediately after creating the Invoice object, although you can optionally authorize first, as described above.

📘

This step is explained with more detail and code samples in the page about capturing a payment.

5. Listening for updates

You can configure Smart Router to send update messages to your server at each stage in fulfilling an order. Use the
information in these messages to keep your database updated, send progress emails to customers, or take any other action required in your workflow.

For example, after capturing, you may find it useful to receive updates about the status of the payment. For card
payments, the PSP will confirm success or failure synchronously as a response to the request. However, a customer
might later open a chargeback, which will effectively cancel the purchase. If you set up your server to receive updates about chargebacks, it can automatically cancel the order or take other appropriate action when a
chargeback occurs.

📘

This step is explained with more detail in the page about using webhooks to respond to events. See the API reference to learn how to create a webhook handler on your server.