API documentation

This comprehensive guide will help you integrate and make the most of our powerful API.
Document
API Swagger
Transaction Feed
Transaction flow
Chat
FAQ

Purpose

Circle K fleet card can be used to effortlessly pay for various services like highway, bridge, or parking tolls. To facilitate all these transactions, the TPN API was created. This document outlines the transaction flow for the TPN API.

 

Glossary

  • POS: Point of Sale (e.g., gas stations, toll collection points, parking facilities)

  • Acquirer Batch: A batch that groups transactions for a specific Partner (e.g., Circle K).

  • POS Batch: A batch that groups transactions for a specific Point of Sale (site), such as a toll booth or parking lot.

 

Transaction flow

  • Open Batches

    The first step in the transaction flow is to open two types of batches:

    • Acquirer Batch: Groups all transactions for a specific Partner (e.g., Circle K).

    • POS Batch: Groups all transactions for a specific Point of Sale (site, such as a gas station, toll collection point, or parking lot).

    Batches are typically opened and closed daily, but they can also be done at other time intervals, such as twice a day, weekly, or monthly.

    Acquirer Batch (B01)
    In step B01, the Partner "opens" the Acquirer batch by assigning a sequence number to this batch. This process is carried out in the Partner's backend system. When performing a transaction, the Partner adds this batch number to each transaction.

    POS Batch (B02)
    In step B02, the Partner "opens" the POS batch by assigning a sequence number to this batch. This process is carried out in the Partner's backend system, but unlike the Acquirer batch, the Partner needs to "open" a POS batch for each site that they own. When performing a transaction, the Partner adds this batch number to each transaction.

    Note: The payment/settlement process occurs only after batches are closed.

  • Enrollment-Tokenization

    • Card Enrollment (Required for Tokenization)

      If tokenization is needed, the first step is to register the payment card using the Card Enrollment Endpoint. This is required only if the customer demands tokenization.

    Endpoint: POST /serviceProviders/{serviceProviderReference}/card/enroll

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    Body Parameters:

    • card: Eazy-Fuel card number used in card enrollment request.

    • enrollmentReference: An optional unique reference for the transaction that can be used to reconcile the EazyFuel transaction with data in the source system. 

     

    Dependencies of the request:

    • Example of a card (if you’ll specify time, token will be expiring after specified time, if not it will be valid until expiration of a card)
    "card": {
    "PAN": "123456789012345678",
    "expiryDate": "07/25"
  }

    • The enrollmentReference returned from this endpoint is used in subsequent requests to reference the card enrollment.

    • The sessionToken is obtained from the response of this endpoint.
    • The verificationCode is obtained from the response of this endpoint.

     

    • Tokenization

      This step converts the card’s sensitive information into a non-sensitive equivalent, known as a token, which will be used in place of the actual card information. This endpoint returns response with a tokenizedPan number which should be further be used as payment token : mobile

    Endpoint: POST /serviceProviders/{serviceProviderReference}/card/enroll

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    Body Parameters:

    • enrollmentReference: An optional unique reference for the transaction that can be used to reconcile the EazyFuel transaction with data in the source system. 
    • card: Eazy-Fuel card number used in card enrollment request.
    • verificationCode: Verification code.
    • sessionToken: Token obtained from the card enrollment response.

     

    Dependencies of the request:

    • The enrollmentReference is obtained from the POST /serviceProviders/{serviceProviderReference}/card/enroll endpoint.

    • The sessionToken is obtained from the response of the POST /serviceProviders/{serviceProviderReference}/card/enroll endpoint.
    • The verificationCode is obtained from the response of the POST /serviceProviders/{serviceProviderReference}/card/enroll endpoint.
    • The tokenizedPan returned by this request should further be used as payment token : mobile
  • Perform Transaction

    When batches are "open," and batch sequence numbers are ready, we can start performing transactions.
    Usually, Authorization and Transaction Capture steps (explained below) are performed for each transaction. In special cases, when Transaction Capture is not needed, only the Authorization step can be performed, for example, to verify the provided card.

     

    • Authorization
      The Authorization Request is sent to verify whether the Circle K fleet card can be used for the requested transaction. It checks for:

      • Card validity

      • Spending limits

      • Time-based restrictions

      • Product-based restrictions

      If the authorization is successful, the transaction can proceed to the next step.

    Endpoint: POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/authorizations

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number. 

    Body Parameters:

    • acquiringInstitutionReference: The Acquiring Institution Id/Reference. 

    • batchReference: Reference of batch used in operations. 

    • currencyCode: The alpha-3 ISO4217 currency code of the contract. (example: EUR)

    • paymentTokens: A list of payment tokens associated with the transaction.

    • productGroups: A list of product groups associated with the transaction.

    • requestDateTimeLocal: Request date time

    • stan: The systems trace audit number from the acquirer. The stan field must be between 1 and 999999.

    Dependencies of the request:

    • Example of a paymentTokens: 

    *(in order to use a PAN card number you need to place it, in a token field)

    "paymentTokens": [
  {
    "type": "None",
    "method": "card",
    "token": "823456789012345678",
    "expiryDate": "07/25"
  },
]


    *(in order to use a Token, you need to place it in a token field like below)

    "paymentTokens": [
  {
    "type": "None",
    "method": "mobile",
    "token": "823456789012345678",
    "expiryDate": null
  },
]

     

    • Example of a productGroups ( this information is passed from Circle K in the integration process):
    "productGroups": [
    {
      "productGroupCode": "string",
      "supplyingCurrency": {
        "retailTotal": {
          "amountGross": 0
        }
      }
    }
  ]

     

    • Example of a requestDateTimeLocal:
    "requestDateTimeLocal": "2024-12-02T03:45:19.820Z"

     

    • The authorizationReference returned from this endpoint is used in subsequent requests to reference the created authorization.
    • The authorizationToken is obtained from this endpoint ( can be provided with a transaction POST request to record the full transaction details )

     

    Endpoint: GET /serviceProviders/{serviceProviderReference}/sites/{siteReference}/authorizations/{authorizationReference}

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number. 

    • authorizationReference: Authorization reference (create authorization request). 

    Dependencies of the request:

    • The authorizationReference is obtained from the POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/authorizations endpoint.

     

    • Reversal
      It is used to unlock funds that were blocked during the authorization. It cannot be performed after capture.
      After a specified period, an automatic reversal is triggered if a capture is not performed following the authorization.
    Endpoint: POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/authorizations/{authorizationReference}/reversal 

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number.

    • authorizationReference: Authorization reference (create authorization request). 

    Dependencies of the request:

    • The authorizationReference is obtained from the POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/authorizations endpoint.

    		 

     

    • Transaction Capture

      In the Transaction Capture step, the transaction details are finalized. This includes capturing:

      • Transaction amount

      • Site reference (the location of the transaction)

      • Acquirer batch number

      • POS batch number

    Endpoint: POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/transaction

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number. 

    Body Parameters:

    • acquiringInstitutionReference: The Acquiring Institution Id/Reference. 

    • batchReference: Reference of batch used in operations. 

    • posBatchReference: The reference of the point-of-sale batch that includes the transaction. (example: 959500)

    • posStan: The systems trace audit number from the point-of-sale. The stan field must be between 1 and 999999. 

    • stan: The systems trace audit number from the acquirer. The stan field must be between 1 and 999999. 

    • supplyingCurrencyCode: The alpha-3 ISO4217 currency code of the contract. (example: EUR)

    • supplyingCurrencyTotal: Total amount in the supplying currency.

    • type: The type of transaction e.g., purchase, refund, deposit, etc.

    • paymentTokens: A list of payment tokens associated with the transaction.

    • lineItems: A list of the individual products purchased.
    • authorizationToken (optional - can be adjusted with configuration if it is required)

     

    Dependencies of the request:

    • Example of a paymentTokens: 

    *(in order to use a PAN card number you need to place it, in a token field, with a method : card)

    "paymentTokens": [
  {
    "type": "None",
    "method": "card",
    "token": "823456789012345678",
    "expiryDate": "07/25"
  },
]


    *(in order to use a Token, you need to place it in a token field like below, with a method : mobile)

    "paymentTokens": [
  {
    "type": "None",
    "method": "mobile",
    "token": "823456789012345678",
    "expiryDate": null
  },
]

         
     
    • Example of a supplyingCurrencyTotal:
    supplyingCurrencyTotal": {
    "amountNet": 0,
    "amountVat": 0,
    "amountGross": 0
  }
    • Example of a lineItems (details about product are being passed by CircleK):
    {
  "lineItems": [
    {
      "productGroupCode": 12345,
      "unitOfMeasure": "L",
      "supplyingCurrency": {
        "retailUnitPrice": {
          "amountNet": 10.000000,
          "amountVat": 2.000000,
          "amountGross": 12.000000
        },
        "retailTotal": {
          "amountNet": 10.000000,
          "amountVat": 2.000000,
          "amountGross": 12.000000
        }
      }
    }
  ]
}
    • The transactionReference returned from this endpoint is used in subsequent requests to reference the created transaction. 
      It should be a unique value. 
      By default, it is created by system, but it could be also added in this request (optional).
    • The authorizationToken is obtained from authorization request

     

    Endpoint: GET /serviceProviders/{serviceProviderReference}/sites/{siteReference}/transactions/{transactionReference} 

    GET /serviceProviders/{serviceProviderReference}/sites/{siteReference}/transactions/{transactionReference}
    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number. 

    • transactionReference: Transaction reference (create transaction request). 

    Dependencies of the request:

    • The transactionReference is obtained from the POST /serviceProviders/{serviceProviderReference}/sites/{siteReference}/transactions


     

     

     

    • Refund

      A refund transaction allows funds to be returned to the cardholder’s account.

    • Refund Request
      The refund request is almost identical to the transaction capture request, with the primary difference being the type field. For a purchase transaction, the type field is set to "purchase," but for a refund transaction, the type field must be set to "refund".

      • Authorization:
        Depending on the configuration in the TPN API, an authorization step may not be required for a refund. If it is required, it follows the same process as the initial authorization, where the card's validity and restrictions are verified before proceeding.
      • Transaction Capture:
        The only change in the Transaction Capture (P06) for refunds is that the type field is set to "refund," and the corresponding amount is refunded to the cardholder. The refunded amount is negative, which will be reflected in the financial settlement, effectively reversing the earlier transaction.

      Note. Refund Behaviour in Batches
      When a refund transaction is performed, it is added to the same batch as the original transaction. The amount for the refund will be recorded with a negative sign to indicate that it is a reversal. This will affect the financial settlement, as the refunded amount will be subtracted from the total batch amount.

  • Close Batches & Reconcile

    During the reconciliation process, check whether the transaction numbers and amounts on both sides (the Partner and Circle K) match.

    • POS Batch Reconciliation
      The Partner closes the POS batch by summing up all transactions associated with that specific POS batch number. Once the batch is closed, the Partner sends the following information to Circle K for reconciliation:

      • Site reference

      • POS batch reference

      • Total amount of transactions

     

     
    Endpoint: POST/PATCH  /serviceProviders/{serviceProviderReference}/sites/{siteReference}/batches/{batchReference} 

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • siteReference: Site reference number. 

    • batchReference: posBatchReference number. 


    Body Parameters:

    • externalProps: External properties for the batch.

     

    Dependencies of the request:

    • Example of externalProps:
    externalProps: {
  "externalProps": {
    "siteNumber": "63999",
    "countryCode": "428",
    "reportNo": 300008984,
    "uniqueId": 970448644,
    "dayPeriod": [
      {
        "deliveryNotes": {
          "paymentMethod": [
            {
              "paymentMethodId": "8",
              "homeCurrency": {
                "numberOfTrans": 1,
                "totalAmount": 35.2
              }
            }
          ]
        }
      }
    ]
  }
}

    *paymentMethodId is provided by a CircleK
    *reportNo as it you should place posBatchReference number

    		 

     

    • Acquirer Batch Reconciliation

      The Partner also closes the Acquirer batch by summing up all transactions associated with the batch number. The following information is sent for reconciliation:

      • Acquirer reference

      • Acquirer batch reference

      • Total amount of transactions
    Endpoint: POST /serviceProviders/{serviceProviderReference}/acquirers/{acquiringInstitutionReference}/batches/{batchReference} 

    Path Parameters:

    • serviceProviderReference: A network owner/operator managing a collection of sites/fuel service stations acquiring transactions from cards being used at that set of sites. 

    • acquiringInstitutionReference: The Acquiring Institution Id/Reference. 

    • batchReference: Reference of batch used in operations. 
      Body Parameters:

    • acquiringInstitutionReference: The Acquiring Institution Id/Reference. 

    • batchReference: Reference of batch used in operations. 

    • summary: Summary of the batch reconciliation.
       

    Dependencies of the request:

    • Example of a summary:
    {
  "summary": {
    "transaction": {
      "total": 1000.50,
      "count": 5
    },
    "transactionReversal": {
      "total": 200.00,
      "count": 2
    },
    "payment": {
      "total": 800.00,
      "count": 4
    },
    "paymentReversal": {
      "total": 150.00,
      "count": 1
    }
  }
}

     

     

     

  • Perform Settlement & Invoicing

    Once the batches have been reconciled, Circle K processes the final steps: settlement and invoicing.

    • Settlement
      In this step, Circle K performs the settlement process and pays the Partner for performed transactions.
    • Invoicing
      In this step, Circle K invoices their customers for performed transactions.

 

Diagram

 

diagram