Payment Types API Reference - Kibo Documentation

Kibo supports many payment types, which shoppers can use to provide payments for their orders. This guide is designed to assist in building the payloads to support creating these payments. Every payment is described by a BillingInfo object. The paymentType field selects the kind of payment, and a type-specific sub-object (such as card, check, or purchaseOrder) carries the details for that type. For where these objects appear in a request and the actions you can perform against a payment, see Payment Actions and the Commerce/OMS API Developer Guide.

Supported Payment Types

The paymentType field accepts one of the following string values. Values are case-sensitive and must be sent exactly as shown.

`paymentType` value	Description
`CreditCard`	Credit or debit card payment, typically tokenized by a payment gateway.
`Check`	Check by mail.
`StoreCredit`	Store credit or loyalty credit applied to the order.
`PaypalExpress`	PayPal Express checkout, using a redirect flow.
`PurchaseOrder`	B2B purchase order drawn against a customer credit limit.
`GiftCard`	Gift card processed through a payment gateway.
`Token`	Tokenized payment from a digital wallet or third-party provider (for example, Apple Pay).

Each payment type must also be enabled and assigned to a gateway for the site before it can be used. See Payment Types for the admin configuration steps.

The BillingInfo Wrapper

BillingInfo is the outer object that wraps every payment. The fields below apply to all payment types; the type-specific sub-objects are described in the sections that follow.

Field	Type	Description
`paymentType`	string	One of the supported payment type values. Required.
`paymentWorkflow`	string	The workflow that processes the payment. Use `"Mozu"` for the default Kibo gateway flow; other built-in values include `"VisaCheckout"` and `"PayPalExpress"`. A custom payment extension supplies its own workflow name.
`billingContact`	object	The billing name, address, and contact details. See billingContact.
`isSameBillingShippingAddress`	boolean	Indicates that the billing and shipping addresses are the same.
`isRecurring`	boolean	Indicates that the payment is used in recurring transactions, such as subscription payments.
`card`	object	Card details. Present only when `paymentType` is `CreditCard`. See CreditCard.
`check`	object	Check details. Present only when `paymentType` is `Check`. See Check.
`token`	object	Token details. Present only when `paymentType` is `Token`. See Token.
`purchaseOrder`	object	Purchase order details. Present only when `paymentType` is `PurchaseOrder`. See PurchaseOrder.
`storeCreditCode`	string	The store credit code to apply. Used when `paymentType` is `StoreCredit`. See StoreCredit.
`storeCreditType`	string	The type of store credit applied. Used with `StoreCredit`.
`customCreditType`	string	The name of a custom stored credit type, when applicable.
`externalTransactionId`	string	A transaction ID from a third-party payment source, such as Visa Checkout or Amazon Pay.
`data`	object	Custom data passed through from payment providers.

Raw card numbers are never sent to Kibo. Card payments reference a tokenized card ID returned by the payment gateway. See CreditCard for details.

The billingContact Object

billingContact carries the payer’s name and billing address. It is shared by all payment types.

{
  "firstName": "Jane",
  "lastNameOrSurname": "Shopper",
  "email": "jane.shopper@example.com",
  "companyOrOrganization": "Example Co.",
  "phoneNumbers": {
    "home": "555-0100",
    "mobile": "555-0101",
    "work": "555-0102"
  },
  "address": {
    "address1": "123 Market Street",
    "address2": "Suite 400",
    "cityOrTown": "Austin",
    "stateOrProvince": "TX",
    "postalOrZipCode": "78701",
    "countryCode": "US",
    "addressType": "Commercial"
  }
}

Per-Type Request Formats

Each section below shows the type-specific sub-object schema and a complete BillingInfo example payload. The billingContact is abbreviated as { ... } in the examples; populate it as shown in The billingContact Object.

CreditCard

Card payments use the card sub-object. The card is tokenized by the payment gateway, so paymentServiceCardId holds the gateway card token rather than a raw card number.

Field	Type	Description
`paymentOrCardType`	string	Card type, such as `Visa`, `MasterCard`, `AmericanExpress`, or `Discover`.
`paymentServiceCardId`	string	The tokenized card ID returned by the payment gateway.
`nameOnCard`	string	Cardholder’s name as it appears on the card.
`cardNumberPartOrMask`	string	The visible portion of the card number, for example the last four digits.
`bin`	string	The card’s bank identification number (the leading digits).
`expireMonth`	integer	Month the card expires.
`expireYear`	integer	Year the card expires.
`isTokenized`	boolean	`true` when the card has been tokenized by an external provider.
`isCardInfoSaved`	boolean	`true` when the card is stored in the customer’s account.
`ccLastFour`	string	Last four digits of the card. Used only for OMS-only tenants.

{
  "paymentType": "CreditCard",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "card": {
    "paymentOrCardType": "Visa",
    "paymentServiceCardId": "f3a9c2e84b7d4e1a9c0f5b6d7e8a1234",
    "nameOnCard": "Jane Shopper",
    "cardNumberPartOrMask": "1111",
    "bin": "411111",
    "expireMonth": 12,
    "expireYear": 2030,
    "isTokenized": true,
    "isCardInfoSaved": false,
    "ccLastFour": "1111"
  }
}

Check

Check by mail uses the check sub-object.

Field	Type	Description
`checkNumber`	string	The check number.

{
  "paymentType": "Check",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "check": {
    "checkNumber": "10042"
  }
}

StoreCredit

Store credit is applied with the storeCreditCode and storeCreditType fields on BillingInfo directly. There is no nested sub-object.

Field	Type	Description
`storeCreditCode`	string	The store credit code to apply to the order.
`storeCreditType`	string	The type of store credit, for example `StoreCredit`.
`customCreditType`	string	The name of a custom stored credit type, when applicable.

{
  "paymentType": "StoreCredit",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "storeCreditCode": "SC-ABC12345",
  "storeCreditType": "StoreCredit",
  "customCreditType": null
}

PurchaseOrder

B2B purchase orders use the purchaseOrder sub-object. The purchase order is authorized against the customer account’s configured credit limit, so the payment method must be enabled on both the site and the individual customer account.

Field	Type	Description
`purchaseOrderNumber`	string	The purchase order number.
`paymentTerm`	object	The selected payment term. Contains `code` and `description`.
`customFields`	array	Memo or custom fields. Each entry contains `code`, `label`, and `value`.

{
  "paymentType": "PurchaseOrder",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "purchaseOrder": {
    "purchaseOrderNumber": "PO-00123",
    "paymentTerm": {
      "code": "net30",
      "description": "Net 30"
    },
    "customFields": [
      {
        "code": "department",
        "label": "Department",
        "value": "Finance"
      }
    ]
  }
}

GiftCard

Gift cards are processed through a payment gateway. The BillingInfo sets paymentType to GiftCard, and the gateway gift card details are supplied through the payment’s gatewayGiftCard object. The gatewayGiftCard object has these fields:

Field	Type	Description
`cardNumber`	string	The gift card number.
`cardPin`	string	The gift card PIN.
`amount`	number	The amount to draw from the gift card.
`currencyCode`	string	ISO currency code for the transaction.
`id`	string	Identifier for the gift card record.

{
  "paymentType": "GiftCard",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... }
}

The associated gatewayGiftCard on the payment:

{
  "cardNumber": "6006491234567890",
  "cardPin": "1234",
  "amount": 25.00,
  "currencyCode": "USD"
}

Gift card behavior, including whether refunds and credits are issued to the existing card or a new one, is configured per site. See Gateway Gift Cards.

Token

Digital wallet and third-party tokenized payments (for example, Apple Pay) use the token sub-object.

Field	Type	Description
`paymentServiceTokenId`	string	The token returned by the payment provider.
`type`	string	The token type or source, for example `ApplePay`.

{
  "paymentType": "Token",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "token": {
    "paymentServiceTokenId": "tok_9c0f5b6d7e8a1234",
    "type": "ApplePay"
  }
}

For some third-party sources, the transaction ID is carried on BillingInfo.externalTransactionId (for example, Visa Checkout or Amazon Pay) rather than in the token object.

PaypalExpress

PayPal Express uses a redirect flow rather than a sub-object on BillingInfo. The BillingInfo sets paymentType to PaypalExpress, and the redirect URLs are supplied on the payment action through returnUrl and cancelUrl. The billingContact is typically populated after PayPal redirects the shopper back to your site.

{
  "actionName": "CreatePayment",
  "amount": 99.99,
  "returnUrl": "https://t1000000.sb.usc1.gcp.kibocommerce.com/checkout/paypal/return",
  "cancelUrl": "https://t1000000.sb.usc1.gcp.kibocommerce.com/checkout/paypal/cancel",
  "newBillingInfo": {
    "paymentType": "PaypalExpress",
    "paymentWorkflow": "PayPalExpress"
  }
}

Where BillingInfo Appears in a Request

BillingInfo is submitted in a few different places depending on the operation:

Applying a payment to an order or checkout: wrapped in a PaymentAction as newBillingInfo, alongside the actionName and amount. See Payment Actions.
Importing a completed order: included on each entry of the order’s payments array and on the order’s billingInfo. See the Commerce/OMS API Developer Guide.

The actionName field on a payment action accepts one of these values: CreatePayment, AuthorizePayment, AuthAndCapture, CapturePayment, CreditPayment, DeclinePayment, RequestCheck, VoidPayment, Rollback, and AcknowledgeError. To create and authorize a new payment from a BillingInfo, use CreatePayment. A minimal payment action that applies a credit card payment looks like this:

{
  "actionName": "CreatePayment",
  "amount": 99.99,
  "currencyCode": "USD",
  "newBillingInfo": {
    "paymentType": "CreditCard",
    "paymentWorkflow": "Mozu",
    "billingContact": { ... },
    "card": {
      "paymentOrCardType": "Visa",
      "paymentServiceCardId": "f3a9c2e84b7d4e1a9c0f5b6d7e8a1234",
      "nameOnCard": "Jane Shopper",
      "cardNumberPartOrMask": "1111",
      "expireMonth": 12,
      "expireYear": 2030,
      "isTokenized": true
    }
  }
}

Payments: Conceptual Guide — how the payment subsystem authorizes, captures, voids, and refunds transactions.
Payment Overview — the payment lifecycle within order management.
Payment Types — enabling and configuring each payment type per site.
Payment Actions — voiding, capturing, crediting, and refunding payments.
Commerce/OMS API Developer Guide — importing completed orders with pre-authorized payments.

​Supported Payment Types

​The BillingInfo Wrapper

​The billingContact Object

​Per-Type Request Formats

​CreditCard

​Check

​StoreCredit

​PurchaseOrder

​GiftCard

​Token

​PaypalExpress

​Where BillingInfo Appears in a Request

​Related Guides

Supported Payment Types

The BillingInfo Wrapper

The billingContact Object

Per-Type Request Formats

CreditCard

Check

StoreCredit

PurchaseOrder

GiftCard

Token

PaypalExpress

Where BillingInfo Appears in a Request

Related Guides