Authorization

This endpoint is used to authorize a payment transaction. It requires a JSON payload containing transaction details, order information, and point-of-sale (POS) data.

The URL for this endpoint is https://api.firstoken.co/v1/payments

In case of sandbox environment you should use this URL: https://api.firstoken-staging.co/v1/payments

Request Headers

• Content-Type: application/json

• x-api-key: <Your API Key>

Attributes of the request

• transaction_info {object}

  • type Type of transaction. Possible values: authorization.

  • reference_code Unique reference code for the transaction.

• order_info {object}

  • amount_details {object}

    • total_amount Total amount to be authorized.

    • currency Currency code (e.g., MXN for Mexican Peso).

• pos {object}

  • entry_mode Method of entering payment card information into the POS terminal. Possible values:

    • contact: Read directly from the chip card via contact.

    • contactless: Read from a contactless interface using chip data.

    • keyed: Manually entered into the POS terminal.

    • msd: Read from a contactless interface using magnetic stripe data (MSD).

    • swiped: Read from the magnetic stripe of the credit card.

    Note: The values contact, contactless, and msd are compatible only for EMV transactions.

  • term_capability POS terminal capability. Possible values:

    • 1: The terminal has only a magnetic stripe reader.

    • 2: The terminal has a magnetic stripe reader and manual input capability.

    • 3: The terminal has only manual input capability.

    • 4: The terminal can read chip cards.

    • 5: The terminal can read chip cards contactlessly; cannot use contact to read chip cards.

    Note: For an EMV transaction, the value of this field must be 4 or 5.

  • cat_level Card acceptance terminal (CAT) level.

    Possible values:

    • 1: Automated dispensing machine

    • 2: Self-service terminal

    • 3: Limited amount terminal

    • 4: In-flight commerce (IFC) terminal

    • 5: Radio frequency device

    • 6: Mobile acceptance terminal

    • 7: Electronic cash register

    • 8: E-commerce device at your location

    • 9: Terminal or cash register that uses a dialup connection to connect to the transaction processing network

  • emv {object}

    • tags EMV tags.

    • verification_method EMV verification method.

    • sequence_number Sequence number for the transaction.

  • track_data Track data from the card.

  • verification_method Complete list of cardholder verification methods (CVM) supported by the terminal.

    Possible Values:

    • PIN: For terminals with a PIN keypad.

    • Signature: For terminals capable of receiving a signature.

    • pinOnGlass: For terminals where the PIN is entered on a glass-based capture mechanism.

    Example:

    • ["PIN", "Signature"]

  • term_input_capability List of terminal input capabilities supported by the terminal.

    • Possible Values:

      • Keyed: The terminal can accept card data entered manually.

      • Swiped: The terminal can accept card data from a magnetic stripe reader.

      • Contact: The terminal can accept card data in contact mode EMV (card insertion).

      • Contactless: The terminal can accept card data in contactless mode EMV (card tap).

      • BarCode: The terminal can read barcodes.

      • QRcode: The terminal can read or scan QR codes.

      • OCR: The terminal can perform optical character recognition (OCR) on the card.

    Example:

    • ["Keyed", "Swiped", "Contact", "Contactless"]

  • term_card_capture_capability Indicates whether the terminal can capture the card.

    • Possible Values:

      • 1: The terminal can capture the card.

      • 0: The terminal cannot capture the card.

  • device_id Unique value created by the client software to identify the POS device.

  • encrypted_key_serial_number Combination of the unique device identifier and a transaction counter used in the process of decrypting the encrypted PIN. The entity that injected the PIN encryption keys into the terminal decrypts the encrypted PIN and creates this value

Attributes of the response

• status: Status of the response. Possible values: success, error.

• message: Message describing the result of the transaction.

• data

  • transaction_info

    • type: Type of transaction response. Possible values: authorization_response.

    • reference_code: Unique reference code for the transaction.

    • transaction_id: Unique transaction ID.

    • request_id: Unique request ID.

    • status: Status of the transaction. Possible values: Authorized, Declined, Pending.

    • response_code: Response code from the processor.

    • reconciliation_id: Reconciliation ID for the transaction.

    • created_at: Timestamp of when the transaction was created.

  • order_info

    • amount_details

      • authorized_amount: Authorized amount.

      • currency: Currency code.

  • processor_info

    • approval_code: Approval code from the processor.

    • avs

      • code: Address verification system code.

Request Body

The request body should be a JSON object with the following structure:

Example of the request

{
  "transaction_info": {
    "type": "authorization",
    "reference_code": "123456789"
  },
  "order_info": {
    "amount_details": {
      "total_amount": 1000,
      "currency": "MXN"
    }
  },
  "pos": {
    "entry_mode": "contactless",
    "term_capability": "2",
    "cat_level": "1",
    "emv": {
      "tags": "9F3303204000950500000000009F3704518823719F10070601",
      "verification_method": 0,
      "sequence_number": "999"
    },
    "track_data": "%B38000000000006^TEST/CYBS ^2512121019761100 00868000000?;3800000000006=25121210197611868000?",
    "verification_method": ["PIN", "Signature"],
    "term_input_capability": ["Contact", "Contactless", "Keyed", "Swiped"],
    "term_card_capture_capability": 1,
    "device_id": "123lkjdIOBK34981slviLI39bj",
    "encrypted_key_serial_number": "1043191"
  }
}

Response

The response will be a JSON object with the following structure:

Example of the response

{
  "status": "success",
  "message": "Authorization successful",
  "data": {
    "transaction_info": {
      "type": "authorization_response",
      "reference_code": "123456789",
      "transaction_id": "0001733510550839298099",
      "request_id": "7335105529856261404953",
      "status": "Authorized",
      "response_code": "00",
      "reconciliation_id": "QCGq6V11TNsW",
      "created_at": "2024-12-06T18:42:33Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 1000,
        "currency": "MXN"
      }
    },
    "processor_info": {
      "approval_code": "123456",
      "avs": {
        "code": "G"
      }
    }
  }
}

Error Handling

In case of an error, the response will have a status of fail and a descriptive message. The data object provides more details about the specific issues encountered.