---
agentTools:
  projectIndex: https://docs.bictorys.com/llms.txt
---

# Returns a settlement details

Use this endpoint to retrieve details of a transaction.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Balance",
    "description": "Bictorys Balance API allows to retrieve merchant balance and  balance transactions (settlements).",
    "version": "1.0.0",
    "x-bictorys-api-type": "public",
    "x-bictorys-api-product": "balance"
  },
  "servers": [
    {
      "url": "https://api.test.bictorys.com/balance-management/v1",
      "description": "Test Environment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Transaction",
      "description": "Settlement transactions"
    }
  ],
  "paths": {
    "/transactions/{transactionId}": {
      "get": {
        "tags": [
          "Transaction"
        ],
        "summary": "Returns a settlement details",
        "description": "Use this endpoint to retrieve details of a transaction.\n",
        "operationId": "getTransactionDetails",
        "parameters": [
          {
            "name": "transactionId",
            "in": "path",
            "description": "Unique identifier of the transaction Id.\n",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Transaction details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionObject"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestError"
                }
              }
            }
          },
          "401": {
            "description": "The caller is unauthenticated"
          },
          "403": {
            "description": "Access rights not sufficient"
          },
          "404": {
            "description": "Card not found"
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TransactionObject": {
        "type": "object",
        "properties": {
          "id": {
            "description": "Unique identifier of the transaction",
            "type": "string",
            "format": "uuid",
            "example": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad"
          },
          "merchantId": {
            "description": "Unique Merchant Identifier",
            "type": "string",
            "format": "uuid",
            "example": "d2d2053b-638d-4133-957e-3caf63e6b79c"
          },
          "type": {
            "description": "type of transaction",
            "$ref": "#/components/schemas/TransactionType",
            "example": "payment"
          },
          "customerId": {
            "description": "Identifier of the customer who paid the transaction",
            "type": "string",
            "format": "uuid",
            "example": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad"
          },
          "customerObject": {
            "description": "customer details",
            "$ref": "#/components/schemas/CustomerObject"
          },
          "pspName": {
            "description": "The PSP, mobile money or card,  used for this transaction",
            "type": "string",
            "enum": [
              "card",
              "orange_money",
              "wave_money",
              "mtn_money",
              "move_money",
              "free_money",
              "visa_card",
              "mastercard_card",
              "bictorys"
            ],
            "example": "card"
          },
          "paymentMeans": {
            "description": "means of transaction",
            "type": "string",
            "example": "+221 *** ** 09"
          },
          "paymentChannel": {
            "description": "Channel used to make the payment",
            "type": "string",
            "enum": [
              "Terminal",
              "Online"
            ],
            "example": "Terminal"
          },
          "amount": {
            "description": "This is the amount received or paid by the merchant, net of fees.",
            "type": "number",
            "format": "double",
            "example": 100
          },
          "merchantFees": {
            "description": "The fee paid by the merchant for receiving the payment.",
            "type": "number",
            "format": "double",
            "example": 2.5
          },
          "customerFees": {
            "description": "The fee paid by the customer for receiving the payment.",
            "type": "number",
            "format": "double",
            "example": 1
          },
          "currency": {
            "description": "The currency associated to the amount. If you don't specify a value, we'll assume 'XOF'",
            "type": "string",
            "example": "XOF"
          },
          "paymentReference": {
            "description": "payment Reference",
            "type": "string",
            "example": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad"
          },
          "merchantReference": {
            "description": "reference passed by client in the request",
            "type": "string",
            "example": "33e1c83b-7cb0-437b-bc50-a7a58e5660ad"
          },
          "orderType": {
            "$ref": "#/components/schemas/OrderType",
            "example": "invoice"
          },
          "orderId": {
            "type": "string",
            "description": "unique Id of the order. invoiceId, orderId or paymentlinkId. This value is empty if orderType equals to flat",
            "example": "14e1c83b-7cb0-437b-bc50-a7a58e5660ad"
          },
          "status": {
            "description": "status of the transaction",
            "$ref": "#/components/schemas/PaymentStatus",
            "example": "succeeded"
          },
          "originIp": {
            "description": "IP address of the device that have sent the request",
            "type": "string",
            "example": "192.0.0.1"
          },
          "timestamp": {
            "description": "The time and date that  the the transaction was recorded in our system. Note that this doesn't describe when payments were executed, only when they were submitted",
            "type": "string",
            "example": "2022-06-20T17:17:11Z"
          }
        },
        "required": [
          "pspName",
          "status",
          "timestamp"
        ]
      },
      "OrderType": {
        "description": "Reference to the type of the payment, invoice, paymentlink, order, flat means the merchant did not create an order or an invoice or a paymentlink prior to call charges API.",
        "type": "string",
        "enum": [
          "flat",
          "order",
          "invoice",
          "paymentlink"
        ],
        "example": "invoice"
      },
      "CustomerObject": {
        "type": "object",
        "properties": {
          "id": {
            "description": "unique uuid of the customer",
            "readOnly": true,
            "type": "string",
            "format": "uuid",
            "example": "fbd2053b-638d-4133-957e-3caf63e6b79c"
          },
          "name": {
            "description": "customer's full name",
            "type": "string",
            "example": "John Dao"
          },
          "phone": {
            "description": "customer's mobile phone number.",
            "type": "string",
            "example": 22505234567890
          },
          "email": {
            "description": "the email of the customer",
            "type": "string",
            "example": "john.dao@example.com"
          },
          "address": {
            "description": "Full street address, which MAY include house number, street name, Post Office Box, etc",
            "type": "string",
            "example": "23, avenue de la liberté"
          },
          "city": {
            "description": "City or locality component.",
            "type": "string",
            "example": "Dakar"
          },
          "postalCode": {
            "description": "Zip code or postal code component.",
            "type": "string",
            "example": 0
          },
          "country": {
            "description": "ISO3166-1 alpha-2 two letter, uppercase.",
            "type": "string",
            "example": "SN"
          },
          "locale": {
            "description": "User locale, language is lower case. Country in upper case",
            "type": "string",
            "default": "en-US",
            "example": "fr-FR"
          },
          "createdAt": {
            "description": "The date time that record was created in our system.",
            "type": "string",
            "readOnly": true,
            "example": "2022-06-20T17:17:11Z"
          },
          "updatedAt": {
            "description": "The date time that record was updated in our system.",
            "type": "string",
            "readOnly": true,
            "example": "2022-06-20T17:17:11Z"
          }
        },
        "required": [
          "country"
        ]
      },
      "TransactionType": {
        "description": "type of transaction",
        "type": "string",
        "enum": [
          "payment",
          "transfer",
          "refund",
          "settlement"
        ]
      },
      "PaymentStatus": {
        "description": "status of the transaction",
        "type": "string",
        "enum": [
          "succeeded",
          "failed",
          "cancelled",
          "pending",
          "processing",
          "reversed",
          "authorized"
        ]
      },
      "BadRequestError": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "example": "Bad request.",
            "default": "Bad request."
          },
          "details": {
            "description": "error details",
            "type": "string",
            "example": "E400-0 card info is missing",
            "enum": [
              "E400-21: representative object is missing",
              "E400-1: merchant name is missing",
              "E400-4: merchant country is missing",
              "E400-2: representative email is missing",
              "E400-1: representative name is missing",
              "E400-0: representative address is missing",
              "E400-0: Unexpected Error",
              "E400-6: Amount is missing",
              "E400-10: Invalid Country format",
              "E400-12: Currency is missing",
              "E400-13: PaymentType is missing",
              "E400-0: NotificationDict is missing",
              "E400-0: Notification value is missing",
              "E400-0: SettingDict is missing",
              "E400-0: Setting value is missing or not allowed",
              "E400-18: IBAN is missing",
              "E400-19: beneficiaryName is missing",
              "E400-0: Header media-type is missing",
              "E400-0: Header Content-Type is missing",
              "E400-22: Unsupported media type. Supported type are pdf, jpeg and png",
              "E400-23: Unsupported media type. use png",
              "E400-16: File size must not exceed 4ko",
              "E400-17: File size must not exceed 1Mo",
              "E400-0: password is missing",
              "E401-1: bearer token or apikey is missing",
              "E401-2: bearer token is missing",
              "E401-4: Cannot delete public key",
              "E400-0: apikey is missing",
              "E403-1: Access right not sufficient",
              "E400-0: Bad id is passed",
              "E400-7: Invalid Name Format",
              "E400-8: Invalid Email Format",
              "E400-9: Invalid phone number Format",
              "E400-3: phone number is required",
              "E400-20: Expired Or Bad OTP or Bad PhoneNumberId",
              "E400-20: Expired Or Bad OTP or Bad MerchantId",
              "E400-20: Expired Or Bad OTP",
              "E403-2: 2FA authentication is required",
              "E409-1 Merchant Representation has already an account",
              "E400-24: Selected Currency is not yet supported for this country",
              "E400-20: Resource is no longer available",
              "E400-25: Payment type is disabled by merchant",
              "E400-0: Bad transactionId is passed",
              "E400-0: Bad transaction type is passed",
              "E400-26: Invoice or Order is paid or expired",
              "E400-27: payment link is paid or expired",
              "E400-0: Missing or Bad search key",
              "E400-28: Money transfer is not authorized for this merchant",
              "E400-0 offline checkout write is missing",
              "E401-1: Invalid Token",
              "E401-3: Invalid apikey",
              "E400-0: type is missing in request body",
              "E400-0: bad or missing scope in request body",
              "E400-0: unknown apikeyId",
              "E400-0: account status is missing",
              "E400-0: merchantId is missing",
              "E400-0: callbackUrl is missing",
              "E400-0: bad type is passed",
              "E400-0: bad cardId is passed",
              "E400-0: bad merchant id is passed",
              "E400-0: unknown or unauthorized permission is passed",
              "E400-0 card info is missing",
              "E400-01: Order name is missing",
              "E400-0: Order id must be in UUID format",
              "E400-0: Same Idempotency is passed",
              "E400-29: product price is missing in a Item line Object",
              "E400-30: product quantity is missing in a Item line Object",
              "E400-31: Due date is required",
              "E400-1: Name is missing",
              "E400-32: Already expired",
              "E404-1: Cannot find resource",
              "E400-33: Wrong payment type or disabled",
              "E400-34: User does not have a secret Code",
              "E400-35: SecretCode is locked, you must reset it",
              "E400-36: Wrong secret code is passed",
              "E400-37: Secret code is missing",
              "E400-38: Insufficient balance",
              "E400-00: country is missing",
              "E400-39: Wrong country is passed",
              "E400-40: Invoice is expired",
              "E400-41: Wrong date format is used",
              "E400-42: Invalid Category format",
              "E400-43: Invalid City format",
              "E400-44:Merchant does not exist",
              "E400-45: Invalid Reference format",
              "E400-46: Invalid paymentReference format",
              "E400-47: Invoice is already paid",
              "E400-48: Payment link already paid",
              "E400-49: Error from PSP, Check your account",
              "E400-50: Amount exceed available capture",
              "E400-51: Wrong secret code is passed",
              "E400-52: You must register you phone number first",
              "E400-53: You don't have a secret code",
              "E400-54: You secret code is locked, do reset",
              "E400-0: Payment failed",
              "E401-5: Your Account is restricted",
              "E401-6: Your Account is not activated"
            ]
          }
        }
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "example": "An error has occurred.",
            "default": "An error has occurred."
          },
          "details": {
            "type": "string",
            "enum": [
              "Technical error on gateway",
              "Technical error on redis",
              "Technical error on database"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 102,
      "1": 31,
      "2": 111,
      "3": 238,
      "4": 252,
      "5": 183,
      "6": 185,
      "7": 0,
      "8": 37,
      "9": 180,
      "10": 132,
      "11": 116
    }
  }
}
```