COconekta
Orders

Create order

Changed on

Create a new order.

post/orders

Request

Headers

Accept-Language'es' | 'en'

Use for knowing which language to use

X-Child-Company-Idstring

In the case of a holding company, the company id of the child company to which will process the request.

Idempotency-Keystring

Unique key to make the request idempotent. Retrying a request with the same key returns the original response instead of performing the operation again.

Request body

currencystring required

Currency with which the payment will be made. It uses the 3-letter code of the International Standard ISO 4217.

metadataobject

Metadata associated with the order. Values must be scalar (string of at most 249 characters, integer, number or boolean); nested objects and arrays are not supported.

needs_shipping_contactboolean

Allows you to fill out the shipping information at checkout

pre_authorizeboolean

Indicates whether the order charges must be preauthorized

processing_modestring

Indicates the processing mode for the order, either ecommerce, recurrent or validation.

return_urlstring uri

Indicates the redirection callback upon completion of the 3DS2 flow. Do not use this parameter if your order has a checkout parameter

reuse_customer_cash_referenceboolean

Reuses the customer's recurrent cash reference (cash_recurrent payment source) in the order's cash charges instead of generating a new reference. Requires customer_info.customer_id.

reuse_customer_clabeboolean

Reuses the customer's recurrent SPEI CLABE (spei_recurrent payment source) in the order's SPEI charges instead of generating a new CLABE. Requires customer_info.customer_id.

three_ds_mode'strict' | 'not_strict' | 'smart'

Indicates the 3DS2 mode: 'strict', 'not_strict' or 'smart'. The value is validated against the allowed set on creation; sending an explicit null is rejected. Omit the field to create the order without requesting 3DS through the API (company-level 3DS applies only to orders paid through Checkout or when antifraud forces 3DS).

Example request

{
  "charges": [
    {
      "amount": 40000,
      "payment_method": {
        "type": "pay_by_bank",
        "expires_at": 1680397724,
        "product_type": "bbva_pay_by_bank"
      }
    }
  ],
  "checkout": {
    "allowed_payment_methods": [
      "cash",
      "card",
      "bank_transfer",
      "bnpl",
      "pay_by_bank",
      "apple",
      "google"
    ],
    "excluded_payment_methods": [
      "cash",
      "bank_transfer"
    ],
    "exclude_card_networks": [
      "visa_master_card"
    ],
    "plan_ids": [
      "plan_123",
      "plan_456"
    ],
    "failure_url": "https://www.mysite.com/failure",
    "monthly_installments_options": [
      3,
      6,
      12
    ],
    "max_failed_retries": 3,
    "on_demand_enabled": true,
    "redirection_time": 10,
    "success_url": "https://www.mysite.com/success"
  },
  "currency": "MXN",
  "customer_info": {
    "name": "DevTest",
    "email": "test@conekta.com",
    "phone": "5522997233",
    "object": "customer_info"
  },
  "discount_lines": [
    {
      "amount": 500,
      "code": "123",
      "type": "loyalty"
    }
  ],
  "fiscal_entity": {
    "address": {
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "external_number": "123"
    },
    "email": "test@gmail.com",
    "name": "Conekta Inc",
    "phone": "+525511223344",
    "tax_id": "AAA010101AAA"
  },
  "line_items": [
    {
      "antifraud_info": {
        "key": "value"
      },
      "brand": "Cohiba",
      "description": "Imported From Mex.",
      "metadata": {
        "key": "value"
      },
      "name": "Box of Cohiba S1s",
      "quantity": 1,
      "sku": "XYZ12345",
      "tags": [
        "food",
        "mexican food"
      ],
      "unit_price": 20000
    }
  ],
  "processing_mode": "ecommerce",
  "return_url": "https://my-website.com",
  "reuse_customer_cash_reference": true,
  "reuse_customer_clabe": true,
  "shipping_contact": {
    "phone": "+525511223344",
    "receiver": "Marvin Fuller",
    "between_streets": "Ackerman Crescent",
    "address": {
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "residential": true
    }
  },
  "shipping_lines": [
    {
      "amount": 100,
      "carrier": "FEDEX",
      "tracking_number": "TRACK123",
      "method": "Same day",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "tax_lines": [
    {
      "amount": 100,
      "description": "testing",
      "metadata": {
        "key": "value"
      }
    }
  ]
}

Response

successful operation

amountinteger required

The total amount to be collected in cents

amount_refundedinteger

The total amount refunded in cents

created_atinteger required

The time at which the object was created in seconds since the Unix epoch

currencystring required

The three-letter ISO 4217 currency code. The currency of the order.

idstring required
is_refundableboolean
livemodeboolean required

Whether the object exists in live mode or test mode

metadataobject

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

objectstring required

String representing the object’s type. Objects of the same type share the same value.

payment_statusstring

The payment status of the order.

processing_modestring

Indicates the processing mode for the order, either ecommerce, recurrent or validation.

updated_atinteger

The time at which the object was last updated in seconds since the Unix epoch

Example response

{
  "amount": 21605,
  "channel": {
    "segment": "Checkout",
    "checkout_request_id": "6fca054a-8519-4c43-971e-cea35cc519bb",
    "checkout_request_type": "HostedPayment",
    "id": "channel_2tNDzhA4Akmzj11AU"
  },
  "charges": {
    "object": "list",
    "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
    "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
    "data": [
      {
        "amount": 4321,
        "channel": {
          "segment": "Checkout",
          "checkout_request_id": "6fca054a-8519-4c43-971e-cea35cc519bb",
          "checkout_request_type": "HostedPayment",
          "id": "channel_2tNDzhA4Akmzj11AU"
        },
        "conekta_account_id": "019ff731-2448-7a6b-b95b-5d4a36035da9",
        "created_at": 1676386026,
        "currency": "MXN",
        "description": "Payment from order",
        "device_fingerprint": "6FR3chaU4Y1nGAW5NAGd1rcjAKa142Ba",
        "failure_code": "suspected_fraud",
        "failure_message": "Este cargo ha sido declinado porque el comportamiento del comprador es sospechoso.",
        "id": "63efa757cf65380001aec040",
        "next_action": {
          "redirect_to_url": {
            "url": "https://pay.conekta.com/6fca054a85194c43971ecea35cc519bb",
            "return_url": "https://my-website.com\""
          },
          "type": "redirect_to_url"
        },
        "object": "charge",
        "order_id": "ord_2tN73UdUSNrYRPD9r",
        "paid_at": 1676390742,
        "payment_method": {
          "object": "payment_source",
          "agreement": "agreement_2tN73UdUSNrYRPD9r",
          "auth_code": 542563,
          "cashier_id": "OINM01010",
          "reference": "93000262276908",
          "barcode_url": "https://barcodes.conekta.com/644ebf80f2243197aad6cd8810375b905b613dbe.png",
          "product_type": "bbva_cash_in",
          "service_name": "store",
          "store": "10MON50EDI",
          "store_name": "wallmart",
          "customer_ip_address": "0.0.0.0"
        },
        "reference_id": "ref_2tN73UdUSNrYRPD9r",
        "refunds": {
          "object": "list",
          "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
          "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
          "data": [
            {
              "amount": -15000,
              "auth_code": "867372",
              "created_at": 1678226878,
              "expires_at": 1678226878,
              "id": "6407b5bee1329a000175ba11",
              "object": "refund",
              "status": "pending"
            }
          ]
        },
        "chargeback": {
          "id": "chbk_2zPxWFUnGNLySoumn",
          "status": "lost",
          "reason": "unrecognized",
          "files": [
            {
              "id": "chbkf_2zPxWFUnGNLySoums",
              "file_name": "20251221500000000000201.pdf",
              "created_at": 1768846800
            }
          ],
          "object": "chargeback",
          "charge_id": "6966a06c044243000156c24d",
          "created_at": 1768846800,
          "evidence_due_by": 1769126399
        },
        "status": "pending_payment"
      }
    ]
  },
  "checkout": {
    "allowed_payment_methods": [
      "cash",
      "card",
      "bank_transfer",
      "bnpl",
      "pay_by_bank",
      "apple",
      "google"
    ],
    "excluded_payment_methods": [
      "cash",
      "bank_transfer"
    ],
    "exclude_card_networks": [
      "visa",
      "amex"
    ],
    "expires_at": 1676613599,
    "failure_url": "http://187.216.228.66:2222/SysVentasPagos/Acceso.aspx",
    "id": "6fca054a-8519-4c43-971e-cea35cc519bb",
    "max_failed_retries": 3,
    "name": "ord-2tNDzhA4Akmzj11AS",
    "object": "checkout",
    "on_demand_enabled": true,
    "redirection_time": 2,
    "slug": "6fca054a85194c43971ecea35cc519bb",
    "success_url": "http://187.216.228.66:2222/SysVentasPagos/Acceso.aspx",
    "starts_at": 1676354400,
    "status": "Issued",
    "type": "HostedPayment",
    "url": "https://pay.conekta.io/checkout/6fca054a85194c43971ecea35cc519bb"
  },
  "created_at": 1676328434,
  "currency": "MXN",
  "customer_info": {
    "object": "customer_info",
    "customer_custom_reference": "custom_reference",
    "name": "DevTest",
    "email": "test@conekta.com",
    "phone": "5522997233",
    "customer_id": "cus_23874283647"
  },
  "discount_lines": {
    "object": "list",
    "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
    "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
    "data": [
      {
        "amount": 500,
        "code": "123",
        "type": "loyalty",
        "id": "dis_lin_2tQQ58HPgPw7StE8z",
        "object": "discount_line",
        "parent_id": "ord_2tPAmKCEJqh8RE6nY"
      }
    ]
  },
  "tax_lines": {
    "object": "list",
    "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
    "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
    "data": [
      {
        "amount": 100,
        "description": "testing",
        "metadata": {
          "key": "value"
        },
        "id": "tax_lin_2tQ8dC5mg1UADmVPo",
        "object": "tax_line",
        "parent_id": "ord_2tPAmKCEJqh8RE6nY"
      }
    ]
  },
  "shipping_lines": {
    "object": "list",
    "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
    "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
    "data": [
      {
        "amount": 100,
        "carrier": "FEDEX",
        "tracking_number": "TRACK123",
        "method": "Same day",
        "metadata": {
          "key": "value"
        }
      }
    ]
  },
  "fiscal_entity": {
    "address": {
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "external_number": "123",
      "object": "fiscal_entity_address"
    },
    "email": "test@gmail.com",
    "name": "Conekta Inc",
    "tax_id": "324234234",
    "id": "fis_ent_2tN85VYaSMyDvjB3M",
    "created_at": 1676328434,
    "object": "fiscal_entity",
    "phone": "+525511223344"
  },
  "id": "ord_2tMtQQpDvfnNjiuFG",
  "line_items": {
    "object": "list",
    "next_page_url": "https://api.conekta.io/resources?limit=10&next=chrg_1",
    "previous_page_url": "https://api.conekta.io/resources?limit=10&previous=chrg_1",
    "data": [
      {
        "antifraud_info": {
          "key": "value"
        },
        "brand": "Cohiba",
        "description": "Imported From Mex.",
        "metadata": {
          "key": "value"
        },
        "name": "Box of Cohiba S1s",
        "quantity": 1,
        "sku": "XYZ12345",
        "tags": [
          "food",
          "mexican food"
        ],
        "unit_price": 20000
      }
    ]
  },
  "next_action": {
    "redirect_to_url": {
      "url": "https://pay.conekta.com/6fca054a85194c43971ecea35cc519bb",
      "return_url": "https://my-website.com\""
    },
    "type": "redirect_to_url"
  },
  "object": "order",
  "payment_status": "paid",
  "processing_mode": "ecommerce",
  "shipping_contact": {
    "created_at": 1675715413,
    "id": "adr_1234567890",
    "object": "shipping_contact",
    "phone": "+525511223344",
    "receiver": "Marvin Fuller",
    "between_streets": "Ackerman Crescent",
    "address": {
      "object": "shipping_address",
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "residential": true
    }
  },
  "updated_at": 1676328434
}

Changes

  • 52f4c0dd8a1bRevision changes
    • breaking

      added subschema #1: shipping_contact_address to the / request property allOf list

    • breaking

      request property was restricted to a list of enum values

    • breaking

      the request property became not nullable

    • breaking

      removed the enum value mastercard of the request property //

    • breaking

      removed the enum value visa of the request property //

    • breaking

      the // request property's maxLength was decreased to 249

    • breaking

      the // request property's minItems was increased to 1

    • breaking

      the // request property's minLength was increased from 0 to 2

    • breaking

      the // request property's minLength was increased from 0 to 3

    • breaking

      the // request property's minLength was increased from 0 to 3

    • breaking

      the // request property's minLength was increased from 0 to 1

    • breaking

      the /// request property's minLength was increased from 0 to 2

    • breaking

      the // request property's minLength was increased from 0 to 3

    • breaking

      the // request property's minLength was increased from 0 to 3

    • breaking

      the // request property's minLength was increased from 0 to 3

    • breaking

      the // request property's minLength was increased from 2 to 3

    • breaking

      added the pattern [A-Za-z]{2} to the request property /

    • breaking

      the response property ///// became optional for the status

    • warning

      the ///// request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      the /// request property's maxLength was set to 249

    • warning

      the / request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      the // request property's maxLength was set to 249

    • warning

      removed the request property /////

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • warning

      removed the request property //

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property ///// became optional

    • info

      added the new not_strict enum value to the request property

    • info

      added the new smart enum value to the request property

    • info

      added the new strict enum value to the request property

    • info

      added the new visa_master_card enum value to the request property //

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status