v1

latestOpenAPI 3.0.22026-07-2667277423.4 KB

Payments

Payment: Finalize

Finalizes a payment.

Finalizes an EMV contact transaction by confirming the chip card's final decision (TC for approved, AAC for declined). Use this after authorization to submit the terminal's transaction outcome and determine whether the payment is captured or cancelled.

post/payments/{id}/finalize

Path parameters

idstring required

A unique 25-character alphanumeric resource identifier.

A unique identifier for the payment.

Request body

captureboolean

ac_type'tc' | 'aac' | 'fault' required

EMV chip card action code: TC (approved), AAC (declined), or fault.

field55string required

EMV tag 55 data from the chip card transaction.

track2string required

Track 2 magnetic stripe equivalent data from the chip card.

metadataobject

Response

200 response

idstring required

A unique 25-character alphanumeric payment identifier.

resource'payment' required

Resource name. Will always be payment.

amountinteger required

The payment amount before tax, greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

taxinteger required

The tax amount, greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

customerstring nullable required

Customer UUID if associated with a customer, otherwise null.

payment_deadlinestring date-time nullable required

Deadline by which the payment must be completed, or null.

payment_method_feeinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

totalinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

currency'JPY' | 'USD' | 'EUR' | 'TWD' | 'KRW' | 'PLN' | 'GBP' | 'HKD' | 'SGD' | 'NZD' | 'AUD' | 'IDR' | 'MYR' | 'PHP' | 'THB' | 'CNY' | 'BRL' | 'CHF' | 'CAD' | 'VND' required

3-letter ISO currency code.

descriptionstring nullable required

A description for this payment. May be null if it's not set.

captured_atstring date-time nullable required

Timestamp when the payment was captured, or null if not yet captured.

external_order_numstring nullable required

Merchant-assigned external order number for this payment.

metadataobject required

Arbitrary key-value metadata attached at payment creation time.

created_atstring date-time required

Timestamp when the payment was created.

amount_refundedinteger required

Amount greater than or equal to 0, in the lowest denomination of the currency (e.g. cents for USD).

locale'ja' | 'en' | 'ko' required

For supported payment methods, sets the language of the instruction page.

sessionstring required

A unique 25-character alphanumeric resource identifier.

customer_family_namestring nullable required

Customer's family name.

customer_given_namestring nullable required

Customer's given name.

mccstring nullable required

Merchant Category Code used for this payment.

Example response

{
  "id": "pay3fj6nnhvws08idzacf6et8",
  "status": "captured",
  "amount": 1000,
  "payment_details": {
    "month": 10,
    "year": 2031,
    "email": "example@komoju.com",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "installments": "3",
    "shipping_address_name": "Taro Tanaka",
    "shipping_address_line1": "5-2-1 Ginza",
    "shipping_address_line2": "3rd floor",
    "shipping_address_city": "Chuo-ku",
    "shipping_address_state": "Tokyo",
    "shipping_address_zip": "170-3293",
    "shipping_address_country": "Japan",
    "billing_address_name": "Taro Tanaka",
    "billing_address_line1": "5-2-1 Ginza",
    "billing_address_line2": "3rd floor",
    "billing_address_city": "Chuo-ku",
    "billing_address_state": "Tokyo",
    "billing_address_zip": "170-3293",
    "billing_address_country": "Japan"
  },
  "currency": "JPY",
  "statement_descriptor": {
    "statement_descriptor": "株式会社KOMOJU",
    "statement_descriptor_alpha": "KOMOJU",
    "statement_descriptor_kana": "コモジュ",
    "statement_city": "Tokyo",
    "contact_phone": "0312345678"
  },
  "platform_details": {
    "submerchants": [
      {
        "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
        "amount": 900,
        "platform_fee": 100
      }
    ]
  },
  "refunds": [
    {
      "id": "ref442o1crn4qn3a3c7gspfik",
      "amount": 1000,
      "currency": "JPY",
      "payment": "pay3fj6nnhvws08idzacf6et8",
      "description": "Full refund",
      "platform_details": {
        "submerchants": [
          {
            "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
            "amount": 900,
            "platform_fee": 100
          }
        ]
      }
    }
  ],
  "refund_requests": [
    {
      "id": "refreqlv6wny1ew1a1aq4zum1",
      "payment": "pay3fj6nnhvws08idzacf6et8",
      "customer_name": "ｻｲﾄｳ ﾏｻﾋﾛ",
      "bank_name": "サンプル銀行",
      "bank_code": "0900",
      "branch_name": "本店",
      "branch_number": "100",
      "account_number": "1234567",
      "status": "completed",
      "platform_details": {
        "submerchants": [
          {
            "submerchant_id": "submerc1od2nc89s6u5hh6x4g",
            "amount": 900,
            "platform_fee": 100
          }
        ]
      }
    }
  ]
}