---
title: "Initiate a payment for a merchant"
method: POST
path: "/charges"
tags: ["Checkout"]
---

# Initiate a payment for a merchant

`POST /charges`

This API endpoint is used to collect payment with mobile money or credit card. The payment can be an invoice,
a payment link or any other type of collect. The request body is defined by the type of collect.
For example, to collect an invoice, just invoiceId is required in the request body.

## Query parameters

- `payment_type` 'wave_money' | 'orange_money' | 'maxit' | 'mtn_money' | 'free_money' | 'moov' | 'mobicash' | 'togocell' | 'bictorys' | 'card'

## Headers

- `X-Amzn-Trace-Id` string

## Request body

- union — The requestBody is one of the following chargeObject or invoiceId or paymentLinkId or orderId and common fields
  - object
    - `amount` number, double — Optional. Amount to be charged.
    - `currency` string — Optional. The currency to charge the customer. Required only if amount above is set.
    - `orderDetails` ItemObject[] — list of purchased items
      - `id` string, uuid — unique uuid of the product
      - `name` string — product name. A product can be a service
      - `reference` string — product reference
      - `price` number, double — product unit price
      - `quantity` number, double — quantity of this product purchased
      - `discount` number, double — discount percentage applied to product price and tax rate
      - `taxRate` number, double — tax rate in percentage added to product price
      - `totalPrice` number, double — total price including discount and tax
    - `paymentReference` string — Optional. Payment reference to be shown on payment page.
    - `deviceId` string — The identifier of the device used to make the payment
    - `customerId` string, uuid — Optional. Unique Id of the customer. If provided, customerObject object below will be ignored.
    - `customerObject` CustomerObject
      - `id` string, uuid — unique uuid of the customer
      - `name` string — customer's full name
      - `phone` string — customer's mobile phone number.
      - `email` string — the email of the customer
      - `address` string — Full street address, which MAY include house number, street name, Post Office Box, etc
      - `city` string — City or locality component.
      - `postalCode` string — Zip code or postal code component.
      - `country` string, required — ISO3166-1 alpha-2 two letter, uppercase.
      - `locale` string — User locale, language is lower case. Country in upper case
      - `createdAt` string — The date time that record was created in our system.
      - `updatedAt` string — The date time that record was updated in our system.
    - `country` string — Recommended. The country where the payment should be processed. For card payment, it's the country where the merchant entity is registered. For mobile Money, it's the country of the customer. If not provided, the country of the merchant is used.
    - `cardObject` CardObject
      - `holderName` string — Full name of card holder as mentioned on the card
      - `number` string — Card Number
      - `expMonth` integer — expiration month of the card
      - `expYear` integer — expiration year of the card
      - `cvv` integer — card verification value.
      - `browserInfo` BrowserInfo — user-agent info used by customer to initiate card payment
        - `browserAcceptHeader` string — accepted header
        - `browserJavaEnabled` boolean — Java enabled
        - `browserLanguage` string — browser language
        - `browserTZ` string — browser time zone
        - `browserUserAgent` string — user-agent
        - `browserColorDepth` string — browser color depth
        - `browserScreenHeight` string — browser Screen Height
        - `browserScreenWidth` string — browser Screen Width
        - `browserJavascriptEnabled` boolean — Is javascript enabled
        - `browserIP` string — browser IP address
        - `challengeWindowSize` string — challengeWindowSize
    - `tokenizedCardObject` TokenizedCardObject — Tokenized card Object used to make tokenized charge with /charges endpoint.
      - `cardId` string, uuid — card Id returned in the response body by Get "#/tokenized-cards".
      - `cvv` integer — card verification value.
    - `authorization` boolean — request approval from card issuer to reserve an amount on the holder card to pay later the transaction. When set to true, an authorization request will be send to card issuer. If ignored or set to false, holder card will be charged immediately
    - `merchantReference` string — Optional. any reference passed by the caller. It will be returned in the response and webhook payload.
    - `successRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is successfully done
    - `errorRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is failed or cancelled. The same url can be used for both succeed and failed transaction
    - `allowUpdateCustomer` boolean — Optional. In the case of checkout or iframe integration, the customer can update phone number or other details, this information are used or the payment. By default, customer profile is not created or updated in this request. If you want that we update customer profile, set allow_update_customer to true. However we recommend to create customer using customer before using charge API
  - object
    - `invoiceId` string — Optional. Unique identifier of the invoice to pay.
    - `country` string — Recommended. The country where the payment should be processed. For card payment, it's the country where the merchant entity is registered. For mobile Money, it's the country of the customer. If not provided, the country of the merchant is used.
    - `cardObject` CardObject
      - `holderName` string — Full name of card holder as mentioned on the card
      - `number` string — Card Number
      - `expMonth` integer — expiration month of the card
      - `expYear` integer — expiration year of the card
      - `cvv` integer — card verification value.
      - `browserInfo` BrowserInfo — user-agent info used by customer to initiate card payment
        - `browserAcceptHeader` string — accepted header
        - `browserJavaEnabled` boolean — Java enabled
        - `browserLanguage` string — browser language
        - `browserTZ` string — browser time zone
        - `browserUserAgent` string — user-agent
        - `browserColorDepth` string — browser color depth
        - `browserScreenHeight` string — browser Screen Height
        - `browserScreenWidth` string — browser Screen Width
        - `browserJavascriptEnabled` boolean — Is javascript enabled
        - `browserIP` string — browser IP address
        - `challengeWindowSize` string — challengeWindowSize
    - `tokenizedCardObject` TokenizedCardObject — Tokenized card Object used to make tokenized charge with /charges endpoint.
      - `cardId` string, uuid — card Id returned in the response body by Get "#/tokenized-cards".
      - `cvv` integer — card verification value.
    - `authorization` boolean — request approval from card issuer to reserve an amount on the holder card to pay later the transaction. When set to true, an authorization request will be send to card issuer. If ignored or set to false, holder card will be charged immediately
    - `merchantReference` string — Optional. any reference passed by the caller. It will be returned in the response and webhook payload.
    - `successRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is successfully done
    - `errorRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is failed or cancelled. The same url can be used for both succeed and failed transaction
    - `allowUpdateCustomer` boolean — Optional. In the case of checkout or iframe integration, the customer can update phone number or other details, this information are used or the payment. By default, customer profile is not created or updated in this request. If you want that we update customer profile, set allow_update_customer to true. However we recommend to create customer using customer before using charge API
  - object
    - `paymentLinkId` string, uuid — unique identifier of the link payment.
    - `country` string — Recommended. The country where the payment should be processed. For card payment, it's the country where the merchant entity is registered. For mobile Money, it's the country of the customer. If not provided, the country of the merchant is used.
    - `cardObject` CardObject
      - `holderName` string — Full name of card holder as mentioned on the card
      - `number` string — Card Number
      - `expMonth` integer — expiration month of the card
      - `expYear` integer — expiration year of the card
      - `cvv` integer — card verification value.
      - `browserInfo` BrowserInfo — user-agent info used by customer to initiate card payment
        - `browserAcceptHeader` string — accepted header
        - `browserJavaEnabled` boolean — Java enabled
        - `browserLanguage` string — browser language
        - `browserTZ` string — browser time zone
        - `browserUserAgent` string — user-agent
        - `browserColorDepth` string — browser color depth
        - `browserScreenHeight` string — browser Screen Height
        - `browserScreenWidth` string — browser Screen Width
        - `browserJavascriptEnabled` boolean — Is javascript enabled
        - `browserIP` string — browser IP address
        - `challengeWindowSize` string — challengeWindowSize
    - `tokenizedCardObject` TokenizedCardObject — Tokenized card Object used to make tokenized charge with /charges endpoint.
      - `cardId` string, uuid — card Id returned in the response body by Get "#/tokenized-cards".
      - `cvv` integer — card verification value.
    - `authorization` boolean — request approval from card issuer to reserve an amount on the holder card to pay later the transaction. When set to true, an authorization request will be send to card issuer. If ignored or set to false, holder card will be charged immediately
    - `merchantReference` string — Optional. any reference passed by the caller. It will be returned in the response and webhook payload.
    - `successRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is successfully done
    - `errorRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is failed or cancelled. The same url can be used for both succeed and failed transaction
    - `allowUpdateCustomer` boolean — Optional. In the case of checkout or iframe integration, the customer can update phone number or other details, this information are used or the payment. By default, customer profile is not created or updated in this request. If you want that we update customer profile, set allow_update_customer to true. However we recommend to create customer using customer before using charge API
  - object
    - `orderId` string — Optional. Unique identifier of the order to pay.
    - `country` string — Recommended. The country where the payment should be processed. For card payment, it's the country where the merchant entity is registered. For mobile Money, it's the country of the customer. If not provided, the country of the merchant is used.
    - `cardObject` CardObject
      - `holderName` string — Full name of card holder as mentioned on the card
      - `number` string — Card Number
      - `expMonth` integer — expiration month of the card
      - `expYear` integer — expiration year of the card
      - `cvv` integer — card verification value.
      - `browserInfo` BrowserInfo — user-agent info used by customer to initiate card payment
        - `browserAcceptHeader` string — accepted header
        - `browserJavaEnabled` boolean — Java enabled
        - `browserLanguage` string — browser language
        - `browserTZ` string — browser time zone
        - `browserUserAgent` string — user-agent
        - `browserColorDepth` string — browser color depth
        - `browserScreenHeight` string — browser Screen Height
        - `browserScreenWidth` string — browser Screen Width
        - `browserJavascriptEnabled` boolean — Is javascript enabled
        - `browserIP` string — browser IP address
        - `challengeWindowSize` string — challengeWindowSize
    - `tokenizedCardObject` TokenizedCardObject — Tokenized card Object used to make tokenized charge with /charges endpoint.
      - `cardId` string, uuid — card Id returned in the response body by Get "#/tokenized-cards".
      - `cvv` integer — card verification value.
    - `authorization` boolean — request approval from card issuer to reserve an amount on the holder card to pay later the transaction. When set to true, an authorization request will be send to card issuer. If ignored or set to false, holder card will be charged immediately
    - `merchantReference` string — Optional. any reference passed by the caller. It will be returned in the response and webhook payload.
    - `successRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is successfully done
    - `errorRedirectUrl` string — Optional. User-agent will be redirected to this url after payment is failed or cancelled. The same url can be used for both succeed and failed transaction
    - `allowUpdateCustomer` boolean — Optional. In the case of checkout or iframe integration, the customer can update phone number or other details, this information are used or the payment. By default, customer profile is not created or updated in this request. If you want that we update customer profile, set allow_update_customer to true. However we recommend to create customer using customer before using charge API

## Response `201`

The payment transaction is initiated. The body response content a confirmation link. Waiting for customer to accept
the payment

- union — Provide instructions to the customer to finalize the payment
  - object
    - `transactionId` string, uuid — Unique Id of the initiated transaction
    - `redirectUrl` string — Customer is redirected to this link after is completed
    - `merchantReference` string — reference passed by client in the request
    - `type` 'MobilePaymentObject' | 'CardPaymentObject' — type of link object
    - `link` string — The payment instruction link URL. Redirect User to this link and we'll provide instructions to accept the payment.
    - `qrCode` string — QR code in base64 to be displayed for customer to allow payment by qrCode. If QrCode is not supported, this field will not be in the response payload
    - `message` string — instruction message to be displayed if link and qrCode field are missing or if you prefer do not redirect user to link url. This field can be omitted.
  - object
    - `transactionId` string, uuid — Unique Id of the initiated transaction
    - `redirectUrl` string — Customer is redirected to this link after is completed
    - `merchantReference` string — reference passed by client in the request
    - `type` 'MobilePaymentObject' | 'CardPaymentObject' — type of link object
    - `state` 'AWAIT_3DS' | 'PURCHASED' | 'CAPTURED' | 'AUTHORIZED' | 'FAILED' | 'DECLINED' — State in the 3DS sequence
    - `3ds` ACS3DSObject — contains objects and url required to perform 3DS1 challenge flow
      - `acsUrl` string — The URL of the issuer’s challenge page
      - `acsPaReq` string — value required by the issuer for providing the challenge to your card-holder.
      - `acsMd` string — uest value required by the issuer for providing the challenge to your card-holder.
      - `acsTerm` string — URL to which the issuer presenting the 3-D Secure challenge will POST the resulting authentication result.
    - `3ds2` ACS3DS2Challenge — 3DS2 block to initiate the challenge flow. If state is AWAIT_3DS, then from an iframe or a new tab POST creq value to acsURL using form url encoded ( Content-Type set to application/x-www-form-urlencoded) Therefore the ACS issuer will display challenge page and complete verification with card hold. The result is sent back to Bictorys payment gateway. Finally Bictorys will redirect to pay.bictorys/card/transactions?status{transactionStatus}. You can intercept the result when shopper clicks on close button.
      - `acsURL` string — The URL of the issuer’s challenge page
      - `creq` string — A Base64 encoded form of the CReq payload

## Other responses

- `202` — The payment request is accepted. The body response content a charge or payment link. Customer is invited to add payment details on the checkout page
- `400` — Bad Request
- `401` — The caller is unauthenticated
- `403` — Access rights not sufficient
- `500` — Internal Server Error.

---

[API](https://skmtc.dev/bictorys/apis/pay.md) · [All operations](https://skmtc.dev/bictorys/apis/pay/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bictorys/pay/revisions/b85cce14340b/schema)