> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Types API Reference

> The complete list of supported payment type values and the exact BillingInfo request format Kibo expects for each, with example payloads for integrators

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](/pages/payment-actions) and the [Commerce/OMS API Developer Guide](/developer-guides/commerce).

## 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). |

<Note>
  Each payment type must also be enabled and assigned to a gateway for the site before it can be used. See [Payment Types](/pages/payment-types) for the admin configuration steps.
</Note>

## 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](#supported-payment-types). 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](#the-billingcontact-object).                                                                                                                         |
| `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](#creditcard).                                                                                                                             |
| `check`                        | object  | Check details. Present only when `paymentType` is `Check`. See [Check](#check).                                                                                                                                           |
| `token`                        | object  | Token details. Present only when `paymentType` is `Token`. See [Token](#token).                                                                                                                                           |
| `purchaseOrder`                | object  | Purchase order details. Present only when `paymentType` is `PurchaseOrder`. See [PurchaseOrder](#purchaseorder).                                                                                                          |
| `storeCreditCode`              | string  | The store credit code to apply. Used when `paymentType` is `StoreCredit`. See [StoreCredit](#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.                                                                                                                                                                        |

<Warning>
  Raw card numbers are never sent to Kibo. Card payments reference a tokenized card ID returned by the payment gateway. See [CreditCard](#creditcard) for details.
</Warning>

### The billingContact Object

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

```json theme={null}
{
  "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](#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.              |

```json theme={null}
{
  "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. |

```json theme={null}
{
  "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. |

```json theme={null}
{
  "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](/pages/purchase-orders).

| 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`. |

```json theme={null}
{
  "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.   |

```json theme={null}
{
  "paymentType": "GiftCard",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... }
}
```

The associated `gatewayGiftCard` on the payment:

```json theme={null}
{
  "cardNumber": "6006491234567890",
  "cardPin": "1234",
  "amount": 25.00,
  "currencyCode": "USD"
}
```

<Note>
  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](/pages/gateway-gift-cards).
</Note>

### 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`. |

```json theme={null}
{
  "paymentType": "Token",
  "paymentWorkflow": "Mozu",
  "billingContact": { ... },
  "token": {
    "paymentServiceTokenId": "tok_9c0f5b6d7e8a1234",
    "type": "ApplePay"
  }
}
```

<Note>
  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.
</Note>

### 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.

```json theme={null}
{
  "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](/pages/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](/developer-guides/commerce).

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:

```json theme={null}
{
  "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
    }
  }
}
```

## Related Guides

* [Payments: Conceptual Guide](/concept-guides/payments) — how the payment subsystem authorizes, captures, voids, and refunds transactions.
* [Payment Overview](/pages/payment-overview) — the payment lifecycle within order management.
* [Payment Types](/pages/payment-types) — enabling and configuring each payment type per site.
* [Payment Actions](/pages/payment-actions) — voiding, capturing, crediting, and refunding payments.
* [Commerce/OMS API Developer Guide](/developer-guides/commerce) — importing completed orders with pre-authorized payments.