Order API Payload and Examples
| Field | Mandatory? | Description |
|---|---|---|
| state | Yes | String containing state of the order. Allowed values are null (indicating no change) and 'confirmed'. (string or null) |
| merchant | Yes | Fields describing the merchant and the store integration. |
| .id | Yes | Merchant identifier. Also called merchant_ref. Example: "s1". (string or int) |
| .notify_url | No | SeQura will make an IPN POST to this URL when the order is approved. The shop should use this signal to confirm the order. Example: "https://my.shop.tld/checkout/sequra-ipn/8765432". (an HTTPS URL string) |
| .notification_parameters | No | Optional name/value pairs that will be included in the IPN POST. Example: {"cart":"1234", "signature":"K6hDNSwfcJjF+suAJqXAjA=="}. (string/string mapping) |
| .return_url | No | The shopper will be redirected to this URL once the shop has confirmed the order after IPN notification. This field is recommended when using IPN. Example: "https://my.shop.tld/checkout/confirmed". (string) |
| .approved_callback | No | Name of Javascript function to call when SeQura approves the order and checkout should move to next step. Can be used with or without IPN. *Cannot* be used with part-payment. Example: "shop_callback_sequra_approved". (string) |
| .edit_url | No | URL for a page where the shopper can edit their name, address, etc. If provided, a link to this URL will be displayed just before SeQura's identification form. (string) |
| .abort_url | No | URL for a page where the shopper can pick another payment method. Used when part-payment fails to get credit card details. Example: "https://my.shop.tld/checkout/payment". (string) |
| .rejected_callback | No | Name of Javascript function to call if the shopper is rejected. The function is expected to display the other payment methods. Example: "showHiddenMethods". (string) |
| .partpayment_details_getter | No | Name of Javascript function to call to get the shopper's part-payment details. Example: "partpaymentWidgetDetails". (string) |
| .approved_url | No | When SeQura approves the order, the shopper's browser will make a POST to this URL without arguments. *Not used* when the integration is using IPN. *Not used* when approved_callback is present. Example: "https://my.shop.tld/checkout/approved". (string) |
| .store_ref | ** | Permanent identifier for the store where the checkout takes place. Example: "maquinista". (string) ** Mandatory for multistore merchants, optional for physical stores, not permitted for others. |
| .operator_ref | ** | Permanent identifier for the cashier operating the sales terminal. Only use if the cashier is properly identified, e.g., with password or equivalent. Example: "123-009". (string) ** Mandatory for multistore merchants, optional for physical stores. |
| .tag_ref | ** | Identifier provided by the cashier operating the sales terminal. Used for debugging and statistics. May be a token shared by several cashiers and does not have to be validated by password or equivalent. Example: "444333222111". (string) |
| .garage_chain | ** | Chain indentifier for merchant Example: "Reparvehicle". (string) |
| .options | No | Features activated by this merchant in this request. |
| .options.has_jquery | No | Set to true if $ is jQuery 1.7 or above, false otherwise. Defaults to true. Example: true. (true or false) |
| .options.uses_shipped_cart | No | True if the merchant wishes to use the API option that explicitly communicates if some items will be shipped immediately after confirmation (see page Shipping items on checkout in the sidebar).Defaults to false. Example: false. (true or false) |
| .options.addresses_may_be_missing | No | True if the merchant cannot send both addresses (delivery_address and invoice_address) during checkout. SeQura strongly suggests that this option is only used when the payload does not include any of the addresses. Defaults to false. Example: false. (true or false) |
| .options.immutable_customer_data | No | True if the merchant wishes to lock the provided shopper's personal data. Shoppers will not be able to edit this information if provided by the merchant. Defaults to false. Example: false. (true or false) |
| .events_webhook | No | Fields describing how the merchant wants to receive webhook events. |
| .events_webhook.url | Yes | SeQura will make a POST to this URL when an event happens for that order after confirmation. Example: "https://my.shop.tld/checkout/sequra-events/8765432". (an HTTPS URL string) |
| .events_webhook.parameters | No | Optional name/value pairs that will be included in the webhook event POST. Example: {"internal_identifier":"1234", "signature":"K6hDNSwfcJjF+suAJqXAjA=="}. (string/string mapping) |
| .timeout | No | Timeout configuration. If this section is present, the identification form will display a count-down (MM:SS) to this time. When it reaches 0:00, the form will be disabled. |
| .timeout.timeout_at | Yes | After this time, the merchant may not be willing or able to sell the cart contents to the shopper. Example: "2017-06-30T13:50:00+02:00". (ISO8601 formatted timestamp) |
| .timeout.timeout_url | Yes | If the identification form is still visible at the timeout time the shopper will be redirected to this URL after a short delay during which the form displays an error message. Example: "https://my.shop.tld/checkout/sequra-timeout/8765432". (a URL string) |
| .verification_id | ** | Verification ID of the supplier Example: "f409ea21-2cfa-4b68-a197-7483ad321f45". (string) |
| merchant_reference | No | Order id(s) used by the merchant |
| .order_ref_1 | Yes | Merchant reference 1. Example: "ZXCV1234". (string or int) |
| .order_ref_2 | No | Merchant reference 2. Example: "0080-1234-4343-5353". (string or int) |
| .subscription_ref_1 | No | Subscription reference 1. Example: "SUBS00001". (string or int) |
| cart | Yes | Fields describing the shopping cart. |
| .currency | Yes | Name of currency used on the purchase. Example: "EUR". (string) |
| .gift | Yes | Set to true if shopper has indicated that this is a gift. Example: false. (true or false) |
| .order_total_with_tax | Yes | Total value with tax of the items listed below. Example: 5097. (int) |
| .cart_ref | No | Shop's unique id for this basket. Useful if shopper has trouble checking out. Example: "123". (string or int) |
| .subscription_period | No | Minimum duration of the subscription (in months), from the date of activation of subscription. Example: 24. (positive int) |
| .subscription_total_price | No | Total monthly cost of the subscription of the items listed below. Example: 1000. (positive int) |
| .created_at | No | When shopper put the first item in the cart. Example: "2013-10-18T12:25:20+01:00". (string) |
| .updated_at | No | When shopper put the last item in the cart. Example: "2013-10-18T12:25:20+01:00". (string) |
| .items | Yes | List of items in the order. The list can contain zero or more instances of each item type. (list) |
| The lines starting with cart.items.0 describe the API when cart.items.0.type is 'product' or missing. | ||
| .items.0.reference | Yes | A public product id for this item. Example: "12-123-1234". (string or int) |
| .items.0.name | Yes | A description to include in the payment instructions. Example: "Leather Case (iPod nano) - Negro / Chocolate". (string) |
| .items.0.price_with_tax | Yes | Price with tax for one item. Example: 3030. (int) |
| .items.0.quantity | Yes | The number of items ordered by the shopper. Example: 2. (positive int) |
| .items.0.subscription_period | No | Subscription period of item in months. Example: 24. (positive int) |
| .items.0.subscription_price_per_item | No | Subscription cost per month per item. Example: 500. (positive int) |
| .items.0.subscription_price | No | Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int) |
| .items.0.subscription_vat_rate | No | VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int) |
| .items.0.total_with_tax | Yes | Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int) |
| .items.0.downloadable | Yes | Can the buyer access or consume the product without a physical delivery? PDFs, e-tickets, software, etc are downloadable. Example: false. (true or false) |
| .items.0.perishable | No | A product is perishable if it loses its value if it is not delivered on time. Examples are fresh fruit and physical tickets. Example: false. (true or false) |
| .items.0.personalized | No | A product is personalized if it is irreversibly customized in a way that makes it less appealing to most people other than the buyer. Example: false. (true or false) |
| .items.0.restockable | No | A product is restockable if it can be sold to someone else if returned in good condition. Foodstuff is generally not restockable. Example: true. (true or false) |
| .items.0.category | No | Name of category. Will not be shown to shopper. Useful against fraud. Example: "ipod-accesorios". (string) |
| .items.0.description | No | Product description. Will not be shown to shopper. Useful against fraud. Example: "Este estuche de cuero de última moda ...". (string) |
| .items.0.manufacturer | No | Name of manufacturer. Will not be shown to shopper. Useful against fraud. Example: "Apple". (string) |
| .items.0.supplier | No | Name of supplier or provider. Will not be shown to shopper. Useful against fraud. Example: "Mayorista Makro". (string) |
| .items.0.product_id | No | Id from database. Will not be shown to shopper. Sometimes useful if 'reference' varies too much over time. Example: "6". (string or int) |
| .items.0.url | No | Product page URL in your shop. Might be shown to shopper. Useful for customer service. Example: "http://shop.example.com/ipod-accesorios/leather-case". (string) |
| .items.0.tracking_reference | No | A reference to the tracking in which this item will be handed. Example: "first". (string) |
| The lines starting with cart.items.1 describe the API when cart.items.1.type is 'handling'. Note that keys "quantity" and "price_with_tax" are not allowed in this section. |
||
| .items.1.reference | Yes | A unique code that refers to this item. Does not have to exist in the shop catalogue. Example: "seur24". (string or int) |
| .items.1.name | Yes | A name to describe this item. More specific is better, i.e. prefer 'Correos' to 'Envío'. Example: "SEUR entrega en 24 horas". (string) |
| .items.1.total_with_tax | Yes | Price with tax for this handling service. Example: 242. (int) |
| The lines starting with cart.items.2 describe the API when cart.items.2.type is 'invoice_fee'. Note that keys "quantity" and "price_with_tax" are not allowed in this section. |
||
| .items.2.total_with_tax | Yes | Price with tax for the invoice (i1) service. Do not use with product codes other than i1. Example: 295. (int) |
| The lines starting with cart.items.3 describe the API when cart.items.3.type is 'discount'. Note that keys "quantity" and "price_with_tax" are not allowed in this section. |
||
| .items.3.reference | Yes | A unique code that refers to this discount. Can be the discount code. Example: "HALFOFF". (string or int) |
| .items.3.name | Yes | A name to describe this discount. Might be displayed in the payment instructions. Example: "50 % off the full basket!". (string) |
| .items.3.total_with_tax | Yes | Amount that this discount changes the cart value with tax. Should be negative. Example: -750. (negative int) |
| The lines starting with cart.items.4 describe the API when cart.items.4.type is 'other_payment'. Note that keys "quantity" and "price_with_tax" are not allowed in this section. |
||
| .items.4.reference | Yes | A code that refers to this "other" payment. (An "other" payment means that the shopper " \ "has paid part of the cart using some other means of payment, like cash or credit card.) Example: "CASH". (string or int) |
| .items.4.name | Yes | A name to describe this payment. Example: "Paid in cash". (string) |
| .items.4.total_with_tax | Yes | Amount that this payment changes the cart value with tax. Should use opposite sign of any item it pays for. Example: -750. (negative int) |
| The lines starting with cart.items.5 describe the API when cart.items.5.type is 'service'. | ||
| .items.5.reference | Yes | A public id for this service. Example: "NETWORKS-ADMIN-101". (string or int) |
| .items.5.name | Yes | A name to describe this service. Might be displayed in the payment instructions. Example: "Networks Administrator Course". (string) |
| .items.5.ends_on | Yes | Maximum date for the service to be rendered or ended. Example: "2017-06-30". (ISO8601 formatted date) |
| .items.5.ends_in | Yes | Maximum time, from the start of the service, for the service to be rendered or ended. Example: "P3M15D". (ISO8601 formatted period) |
| .items.5.price_with_tax | Yes | Price with tax for one item. Example: 3030. (int) |
| .items.5.quantity | Yes | The number of items ordered by the shopper. Example: 1. (positive int) |
| .items.5.total_with_tax | Yes | Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 75020. (int) |
| .items.5.downloadable | Yes | True for services that can be fully (or sufficiently) enjoyed without a physical delivery. For instance, a course with only digital material. Example: false. (true or false) |
| .items.5.supplier | No | Name of supplier or provider. Example: "Acme Formación". (string) |
| .items.5.rendered | No | True when the service has been rendered Example: false. (true or false) |
| The lines starting with cart.items.9 describe the API when cart.items.9.type is 'subscriber_fee'. | ||
| .items.9.reference | No | A public product id for this item. Example: "12-123-1234". (string or int) |
| .items.9.name | Yes | A description to include in the payment instructions. Example: "Subscription fee". (string) |
| .items.9.price_with_tax | No | Price with tax for one item. Example: 3030. (int) |
| .items.9.quantity | No | The number of items ordered by the shopper. Example: 2. (positive int) |
| .items.9.subscription_period | No | Subscription period of item in months. Example: 24. (positive int) |
| .items.9.subscription_price_per_item | No | Subscription cost per month per item. Example: 500. (positive int) |
| .items.9.subscription_price | No | Total subscription cost per month (subscription_price_per_item * quantity) Example: 1000. (positive int) |
| .items.9.subscription_vat_rate | No | VAT rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (positive int) |
| .items.9.total_with_tax | Yes | Price with tax for the amount in the order. Due to rounding, this might not be exactly quantity × price_with_tax. Example: 6060. (int) |
| trackings | No | A list of trackings for the order. |
| The lines starting with trackings.0 describe the API when trackings.0.type is 'pickup_store'. | ||
| .0.reference | Yes | Internal tracking reference. Example: "first". (string) |
| .0.operator_ref | No | Permanent identifier for the operator that handed the delivery. Example: "123-009". (string) |
| .0.store_ref | No | Permanent identifier for the store that handled this delivery. Example: "maquinista". (string) |
| .0.tracking_number | No | Tracking number. Example: "AB331". (string) |
| .0.available_at | No | When this delivery was available in the store. Example: "2014-02-05T13:21:22+01:00". (ISO8601 formatted timestamp) |
| .0.delivered_at | No | When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp) |
| .0.address_line_1 | No | Address line 1 for the store. Example: "1600 Pennsylvania Avenue". (string) |
| .0.address_line_2 | No | Address line 2 for the store. Example: "5º". (string) |
| .0.postal_code | No | Postal code. Example: "08013". (string) |
| .0.city | No | City. Example: "Barcelona". (string) |
| .0.state | No | State or region. Example: "Barcelona". (string) |
| .0.country_code | No | Country code. Example: "ES". (ISO-3166 alpha-2/3 code) |
| The lines starting with trackings.1 describe the API when trackings.1.type is 'pickup_point'. | ||
| .1.reference | Yes | Tracking reference. Example: "second". (string) |
| .1.operator_ref | No | Permanent identifier for the operator that handed the delivery. Example: "123-009". (string) |
| .1.store_ref | No | Permanent identifier for the store that handled this delivery. Example: "maquinista". (string) |
| .1.tracking_number | No | Tracking number. Example: "AB331". (string) |
| .1.available_at | No | When this delivery was available in the store. Example: "2014-02-05T13:21:22+01:00". (ISO8601 formatted timestamp) |
| .1.delivered_at | No | When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp) |
| .1.address_line_1 | No | Address line 1 for the pickup point. Example: "1600 Pennsylvania Avenue". (string) |
| .1.address_line_2 | No | Address line 2 for the pickup point. Example: "5º". (string) |
| .1.postal_code | No | Postal code. Example: "08013". (string) |
| .1.city | No | City. Example: "Barcelona". (string) |
| .1.state | No | State or region. Example: "Barcelona". (string) |
| .1.country_code | No | Country code. Example: "ES". (ISO-3166 alpha-2/3 code) |
| The lines starting with trackings.2 describe the API when trackings.2.type is 'postal'. | ||
| .2.reference | Yes | Internal tracking reference. Example: "third". (string) |
| .2.carrier | Yes | The name of the company that handled this delivery. Example: "SEUR". (string) |
| .2.tracking_number | No | Tracking number. Example: "TX123". (string) |
| .2.tracking_url | No | Tracking URL. Example: "https://logistics.es/TX123". (an HTTPS URL string) |
| .2.delivered_at | No | When this delivery was handed. When set, the delivey is considered to be handed. Example: "2014-02-05T19:21:22+01:00". (ISO8601 formatted timestamp) |
| delivery_method | Yes | Delivery method used on the purchase. |
| .name | Yes | Name of the delivery method. Example: "SEUR24". (string) |
| .days | No | Days it takes to deliver the goods. Example: "¡Entrega día siguiente!". (string) |
| .provider | No | Company or agent that performs the delivery. Example: "Correos". (string) |
| .home_delivery | No | If goods are delivered to the buyer's home or office and not to a pick-up place. Example: true. (true or false) |
| delivery_address | ** | Fields describing the delivery address. |
| .given_names | Yes | Shopper's given names for delivery. Example: "Maria José". (string) |
| .surnames | Yes | Shopper's last names for delivery. Example: "Barroso Rajoy". (string) |
| .company | Yes | Shopper company name. (string) |
| .address_line_1 | Yes | Delivery address line 1. Example: "C/ Aragó 383". (string) |
| .address_line_2 | Yes | Delivery address line 2. Example: "5º". (string) |
| .postal_code | Yes | Delivery address address postal code. Example: "08013". (string) |
| .city | Yes | Delivery address city. Example: "Barcelona". (string) |
| .country_code | Yes | Delivery address country code. Example: "ES". (string) |
| .phone | No | Shopper phone. Can be a mobile phone. Example: "933 033 033". (string) |
| .mobile_phone | No | Shopper mobile phone. Only use this field if the shopper indicated that this number is a mobile phone. Example: "615 615 615". (string) |
| .state | No | Shopper region or state. Example: "Barcelona". (string) |
| .extra | No | Extra handling information that the shopper adds to the order. Example: "I'm home between 9 and 12.". (string) |
| .vat_number | No | Shopper VAT number. Example: "B12345". (string) |
| invoice_address | ** | Fields describing the invoice address. |
| .given_names | Yes | Shopper's given names for invoice. Example: "Maria José". (string) |
| .surnames | Yes | Shopper's last names for invoice. Example: "Barroso Rajoy". (string) |
| .company | Yes | Shopper company name. (string) |
| .address_line_1 | Yes | Invoice address line 1. (string) |
| .address_line_2 | Yes | Invoice address line 2. (string) |
| .postal_code | Yes | Invoice address address postal code. (string) |
| .city | Yes | Invoice address city. (string) |
| .country_code | Yes | Invoice address country code. Example: "ES". (string) |
| .phone | No | Shopper phone. Can be a mobile phone. Example: "933 033 033". (string) |
| .mobile_phone | No | Shopper mobile phone. Only use this field if the shopper indicated that this number is a mobile phone. Example: "615 615 615". (string) |
| .state | No | Shopper region or state. Example: "Tarragona". (string) |
| .extra | No | Extra handling information that the shopper adds to the order. Example: "I'm home between 9 and 12.". (string) |
| .vat_number | No | Shopper VAT number. Example: "B12345". (string) |
| customer | Yes | Fields describing the customer. |
| .given_names | Yes | Customer given names. Example: "Maria José". (string) |
| .surnames | Yes | Customer surnames. Example: "Barroso Rajoy". (string) |
| .title | No | Customer title and/or gender. Use the one of 'mr', 'ms', 'mrs', 'miss' or 'mx' that is closest to the information supplied by the customer. If none of these can be inferred, use the title that the customer entered as-is. See also 'Note about title' in the docs. Example: "mr". (string) |
| Yes | Customer email. Example: "nisse@example.com". (string) | |
| .logged_in | Yes | Is the customer logged in? Use 'unknown' if your platform cannot check whether the user is logged in or not Example: true. (true, false or unknown) |
| .language_code | Yes | Customer language code. Example: "es-ES". (string) |
| .ip_number | Yes | Customer ip number. Example: "12.23.34.45". (string) |
| .user_agent | Yes | Customer browser. Example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_0) AppleWebKit/537.36". (string or null) |
| .ref | No | Customer reference number in the shop's database. Example: 123. (string or int) |
| .date_of_birth | No | Customer date of birth in ISO-8601 format. Example: "1980-01-20". (string) |
| .nin | No | Customer's national identity number. For Spanish DNI, please include final letter. Example: "13003009L". (string) |
| .company | No | Customer company name. (string) |
| .vat_number | No | Shopper VAT number. Example: "B12345". (string) |
| .created_at | No | Date when this customer was added to the shop database, in ISO-8601 format. Example: "2013-08-15T21:07:37+01:00". (string) |
| .updated_at | No | Date when this customer was updated in the shop database, in ISO-8601 format. Example: "2013-09-27T16:50:25+01:00". (string) |
| .rating | No | The merchant's rating of this customer. 0 to 100, inclusive, where 0 is "cannot be trusted" and 100 is "very trustworthy". Example: 100. (int) |
| .nin_control | No | A validation code printed in the physical DNI or NIE. Required for multistore merchants and physical stores. See the FAQs to know more. Example: "15012018F2". (string) |
| .previous_orders | No | List of customer's previous orders in this shop. (list) |
| .previous_orders.0.created_at | Yes | Date (and time, if available) when this order was created or delivered, in ISO-8601 format. Example: "2013-06-11T12:27:40+02:00". (string) |
| .previous_orders.0.amount | Yes | Total order amount including tax. Example: 4656. (int) |
| .previous_orders.0.currency | Yes | Currency name for amount. Example: "EUR". (string) |
| .previous_orders.0.raw_status | No | The status of the order as reported in the platform. Example: "Shipped". (string) |
| .previous_orders.0.status | No | The mapped status value. Use one of 'processing', 'shipped' or 'cancelled' Example: "shipped". (string) |
| .previous_orders.0.payment_method_raw | No | Payment method as reported by the platform. Example: "PayPal". (string) |
| .previous_orders.0.payment_method | No | Mapped payment methods. Use one of CC (for credit cards), PP (for PayPal), TR (for bank wire), COD (for cash on delivery, contrareembolso), SQ (SeQura). For other methods, use O/ plus a name, e.g. 'O/postal_giro' Example: "PP". (string) |
| .previous_orders.0.postal_code | No | Previous order's delivery address postal code. Example: "08013". (string) |
| .previous_orders.0.country_code | No | Previous order's country code. Example: "ES". (string) |
| .vehicle | ** | Fields describing the customer's vehicle |
| .vehicle.plaque | Yes | Plaque identificator from customer's vehicle Example: "0000AAA". (string) |
| .vehicle.brand | No | Brand from customer's vehicle Example: "Volkswagen". (string) |
| .vehicle.model | No | Model from customer's vehicle Example: "Beetle". (string) |
| .vehicle.frame | No | Frame identificator from customer's vehicle Example: "VF1RFD00653635032". (string) |
| .vehicle.first_registration_date | No | First registration date plaque from customer's vehicle Example: "2000-03-25". (string) |
| instore | ** | Fields describing the In-store integration. |
| .code | Yes | String displayed to the shopper once the order is approved that can be used to identify the purchase. Example: "8324". (string) |
| gui | Yes | Fields describing the medium for which the response will be generated. |
| .layout | Yes | What kind of layout should the API optimise for? Accepted values are 'desktop' and 'smartphone', but more might come in the future. Example: "desktop". (string) |
| platform | Yes | Fields describing the store platform. |
| .name | Yes | Name of the platform. Use your shop name. Plugins for "standard" platforms will use that name. Example: "www.theshop.es". (string) |
| .version | Yes | Version of the platform. If you don't use explicit versioning, use a release date instead. Example: "1.1". (string) |
| .plugin_version | No | Version of the plugin or platform module. If you don't use explicit versioning, use a release date instead. Example: "1.0.2". (string) |
| .uname | Yes | uname of the shop server. In PHP, use php_uname(). Example: "Darwin roatan.local 13.0.0 Darwin Kernel Version 13.0... x86_64". (string) |
| .db_name | Yes | DB used. Example: "mysql". (string) |
| .db_version | Yes | Version of the DB. Example: "1.2.3". (string) |
| .php_version | No | PHP interpreter version. Example: "5.4.1.7". (string) |
| first_charge_date | No | When the first payment for the order should be charged. Example: "2001-01-01". (string) |
| subscription | No | Fields describing the subscription. |
| .cart | No | Fields describing the subscription elements |
| .cart.currency | Yes | Name of currency used on the purchase. Example: "EUR". (string) |
| .cart.items | Yes | List of items in the order. The list can contain zero or more instances of each item type. (list) |
| The lines starting with subscription.cart.items.0 describe the API when subscription.cart.items.0.type is 'product'. | ||
| .cart.items.0.unique_reference | Yes | A unique id for this item in merchant's system. Example: "12-123-1234". (string) |
| .cart.items.0.catalogue_reference | No | SKU or similiar reference from the merchant's catalogue. Example: "IPHONE12BLACK". (string) |
| .cart.items.0.name | Yes | A description to include in generated documents in invoices Example: "Leather Case (iPod nano) - Negro / Chocolate". (string) |
| .cart.items.0.monthly_price_with_tax | Yes | Monthly price of subscription for this item Example: 3030. (int) |
| .cart.items.0.vat_rate | Yes | Vat rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (int) |
| .cart.items.0.minimum_period | Yes | The minimum period of subscription in months. Example: 24. (int) |
| .cart.items.0.extension_period | Yes | The minimum period for extending subscription in months. Example: 3. (int) |
| .cart.items.0.start_on | No | Date when subscription starts Example: "2013-10-18". (string) |
| .cart.items.0.end_on | No | Date when subscription ends Example: "2015-10-18". (string) |
| .cart.items.0.extra | No | Additional details about the subscription. Example: "{}". |
| The lines starting with subscription.cart.items.1 describe the API when subscription.cart.items.1.type is 'subscriber_fee'. | ||
| .cart.items.1.unique_reference | Yes | A unique id for this item in merchant's system. Example: "12-123-1234". (string) |
| .cart.items.1.catalogue_reference | No | SKU or similiar reference from the merchant's catalogue. Example: "IPHONE12BLACK". (string) |
| .cart.items.1.name | Yes | A description to include in generated documents in invoices Example: "Leather Case (iPod nano) - Negro / Chocolate". (string) |
| .cart.items.1.monthly_price_with_tax | Yes | Monthly price of subscription for this item Example: 3030. (int) |
| .cart.items.1.vat_rate | Yes | Vat rate for subscription (multiplied by 100: 2100 for 21%). Example: 2100. (int) |
| .cart.items.1.minimum_period | Yes | The minimum period of subscription in months. Example: 24. (int) |
| .cart.items.1.extension_period | Yes | The minimum period for extending subscription in months. Example: 3. (int) |
| .cart.items.1.start_on | No | Date when subscription starts Example: "2013-10-18". (string) |
| .cart.items.1.end_on | No | Date when subscription ends Example: "2015-10-18". (string) |
| .cart.items.1.extra | No | Additional details about the subscription. Example: "{}". |
| .discounts | No | Discounts applied to the Subscription (list) |
| The lines starting with subscription.discounts.0 describe the API when subscription.discounts.0.type is '["percent", "amount"]'. | ||
| .discounts.0.unique_reference | Yes | A unique id for this discount in merchant's system. Example: "12-123-1234". (string) |
| .discounts.0.promotion_reference | No | Reference of the promotional campaign Example: "three_month_half_off". (string) |
| .discounts.0.amount | Yes | Amount of discount in cents or 1/100 of percent Example: 5000. (int) |
| .discounts.0.start_month | Yes | First month of discount Example: 1. (int) |
| .discounts.0.period_in_months | Yes | Duration of discount in months Example: 3. (int) |
JSON examples
Some integrations use specific features that depend on the contract between the merchant and SeQura. Use the checkboxes below to see a custom example. You can ask your SeQura’s integration buddy about the contract options that affect your integration.
Contract options
- Services: The shop sells a service, i.e., it has an ending date (ends_in or ends_on fields) for the service. F.i, a course.
- Multistore: The shop has a physical store. It may have one or many different stores. This option requires these addtional fields: store_ref, operator_ref and nin_control.
- Garage: Garages have to inform the vehicle's plaque. They are also multistore. The shop requires to add garage_chain field in case it belongs to an specific chain
- Shipment_ref: If your shop makes partial shipments and it wants to track them at disbursement, use this option. Read more.
Generate the payload for your contract options
PHP example
This example includes all options and features available.
$order = array();
$order["state"] = "";
$order["merchant"] = array();
$order["merchant"]["id"] = "s1";
$order["merchant"]["notify_url"] = "https://my.shop.tld/checkout/sequra-ipn/8765432"; // optional
$order["merchant"]["notification_parameters"] = ["cart" => "1234", "signature" => "K6hDNSwfcJjF+suAJqXAjA=="]; // optional
$order["merchant"]["return_url"] = "https://my.shop.tld/checkout/confirmed"; // optional
$order["merchant"]["approved_callback"] = "shop_callback_sequra_approved"; // optional
$order["merchant"]["edit_url"] = ""; // optional
$order["merchant"]["abort_url"] = "https://my.shop.tld/checkout/payment"; // optional
$order["merchant"]["rejected_callback"] = "showHiddenMethods"; // optional
$order["merchant"]["partpayment_details_getter"] = "partpaymentWidgetDetails"; // optional
$order["merchant"]["approved_url"] = "https://my.shop.tld/checkout/approved"; // optional
// $order["merchant"]["store_ref"] = "maquinista"; // Mandatory for multistore merchants, optional for physical stores, not permitted for others.
// $order["merchant"]["operator_ref"] = "123-009"; // Mandatory for multistore merchants, optional for physical stores.
// $order["merchant"]["tag_ref"] = "444333222111"; // contract
// $order["merchant"]["garage_chain"] = "Reparvehicle"; // contract
$order["merchant"]["options"] = array(); // optional
$order["merchant"]["options"]["has_jquery"] = true; // optional
$order["merchant"]["events_webhook"] = array(); // optional
$order["merchant"]["events_webhook"]["url"] = "https://my.shop.tld/checkout/sequra-events/8765432";
$order["merchant"]["events_webhook"]["parameters"] = ["internal_identifier" => "1234", "signature" => "K6hDNSwfcJjF+suAJqXAjA=="]; // optional
$order["merchant"]["timeout"] = array(); // optional
$order["merchant"]["timeout"]["timeout_at"] = "2017-06-30T13:50:00+02:00";
$order["merchant"]["timeout"]["timeout_url"] = "https://my.shop.tld/checkout/sequra-timeout/8765432";
// $order["merchant"]["verification_id"] = "f409ea21-2cfa-4b68-a197-7483ad321f45"; // contract
$order["merchant_reference"] = array(); // optional
$order["merchant_reference"]["order_ref_1"] = "ZXCV1234";
$order["merchant_reference"]["order_ref_2"] = "0080-1234-4343-5353"; // optional
$order["merchant_reference"]["subscription_ref_1"] = "SUBS00001"; // optional
$order["cart"] = array();
$order["cart"]["currency"] = "EUR";
$order["cart"]["gift"] = false;
$order["cart"]["order_total_with_tax"] = 5097;
$order["cart"]["cart_ref"] = "123"; // optional
$order["cart"]["subscription_period"] = 24; // optional
$order["cart"]["subscription_total_price"] = 1000; // optional
$order["cart"]["created_at"] = "2013-10-18T12:25:20+01:00"; // optional
$order["cart"]["updated_at"] = "2013-10-18T12:25:20+01:00"; // optional
$order["cart"]["items"] = array();
$order["cart"]["items"][0] = array();
$order["cart"]["items"][0]["reference"] = "12-123-1234";
$order["cart"]["items"][0]["name"] = "Leather Case (iPod nano) - Negro / Chocolate";
$order["cart"]["items"][0]["price_with_tax"] = 3030;
$order["cart"]["items"][0]["quantity"] = 2;
$order["cart"]["items"][0]["subscription_period"] = 24; // optional
$order["cart"]["items"][0]["subscription_price_per_item"] = 500; // optional
$order["cart"]["items"][0]["subscription_price"] = 1000; // optional
$order["cart"]["items"][0]["subscription_vat_rate"] = 2100; // optional
$order["cart"]["items"][0]["total_with_tax"] = 6060;
$order["cart"]["items"][0]["downloadable"] = false;
$order["cart"]["items"][0]["perishable"] = false; // optional
$order["cart"]["items"][0]["personalized"] = false; // optional
$order["cart"]["items"][0]["restockable"] = true; // optional
$order["cart"]["items"][0]["category"] = "ipod-accesorios"; // optional
$order["cart"]["items"][0]["description"] = "Este estuche de cuero de última moda ..."; // optional
$order["cart"]["items"][0]["manufacturer"] = "Apple"; // optional
$order["cart"]["items"][0]["supplier"] = "Mayorista Makro"; // optional
$order["cart"]["items"][0]["product_id"] = "6"; // optional
$order["cart"]["items"][0]["url"] = "http://shop.example.com/ipod-accesorios/leather-case"; // optional
$order["cart"]["items"][0]["tracking_reference"] = "first"; // optional
$order["cart"]["items"][1] = array();
$order["cart"]["items"][1]["type"] = "handling";
$order["cart"]["items"][1]["reference"] = "seur24";
$order["cart"]["items"][1]["name"] = "SEUR entrega en 24 horas";
$order["cart"]["items"][1]["total_with_tax"] = 242;
$order["cart"]["items"][2] = array();
$order["cart"]["items"][2]["type"] = "invoice_fee";
$order["cart"]["items"][2]["total_with_tax"] = 295;
$order["cart"]["items"][3] = array();
$order["cart"]["items"][3]["type"] = "discount";
$order["cart"]["items"][3]["reference"] = "HALFOFF";
$order["cart"]["items"][3]["name"] = "50 % off the full basket!";
$order["cart"]["items"][3]["total_with_tax"] = -750;
$order["cart"]["items"][4] = array();
$order["cart"]["items"][4]["type"] = "other_payment";
$order["cart"]["items"][4]["reference"] = "CASH";
$order["cart"]["items"][4]["name"] = "Paid in cash";
$order["cart"]["items"][4]["total_with_tax"] = -750;
$order["cart"]["items"][5] = array();
$order["cart"]["items"][5]["type"] = "service";
$order["cart"]["items"][5]["reference"] = "NETWORKS-ADMIN-101";
$order["cart"]["items"][5]["name"] = "Networks Administrator Course";
$order["cart"]["items"][5]["ends_in"] = "P3M15D";
$order["cart"]["items"][5]["price_with_tax"] = 3030;
$order["cart"]["items"][5]["quantity"] = 1;
$order["cart"]["items"][5]["total_with_tax"] = 75020;
$order["cart"]["items"][5]["downloadable"] = false;
$order["cart"]["items"][5]["supplier"] = "Acme Formación"; // optional
$order["cart"]["items"][5]["rendered"] = false; // optional
$order["cart"]["items"][9] = array();
$order["cart"]["items"][9]["type"] = "subscriber_fee";
$order["cart"]["items"][9]["reference"] = "12-123-1234"; // optional
$order["cart"]["items"][9]["name"] = "Subscription fee";
$order["cart"]["items"][9]["price_with_tax"] = 3030; // optional
$order["cart"]["items"][9]["quantity"] = 2; // optional
$order["cart"]["items"][9]["subscription_period"] = 24; // optional
$order["cart"]["items"][9]["subscription_price_per_item"] = 500; // optional
$order["cart"]["items"][9]["subscription_price"] = 1000; // optional
$order["cart"]["items"][9]["subscription_vat_rate"] = 2100; // optional
$order["cart"]["items"][9]["total_with_tax"] = 6060;
$order["trackings"] = array(); // optional
$order["trackings"][0] = array();
$order["trackings"][0]["type"] = "pickup_store";
$order["trackings"][0]["reference"] = "first";
$order["trackings"][0]["operator_ref"] = "123-009"; // optional
$order["trackings"][0]["store_ref"] = "maquinista"; // optional
$order["trackings"][0]["tracking_number"] = "AB331"; // optional
$order["trackings"][0]["available_at"] = "2014-02-05T13:21:22+01:00"; // optional
$order["trackings"][0]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["trackings"][0]["address_line_1"] = "1600 Pennsylvania Avenue"; // optional
$order["trackings"][0]["address_line_2"] = "5º"; // optional
$order["trackings"][0]["postal_code"] = "08013"; // optional
$order["trackings"][0]["city"] = "Barcelona"; // optional
$order["trackings"][0]["state"] = "Barcelona"; // optional
$order["trackings"][0]["country_code"] = "ES"; // optional
$order["trackings"][1] = array();
$order["trackings"][1]["type"] = "pickup_point";
$order["trackings"][1]["reference"] = "second";
$order["trackings"][1]["operator_ref"] = "123-009"; // optional
$order["trackings"][1]["store_ref"] = "maquinista"; // optional
$order["trackings"][1]["tracking_number"] = "AB331"; // optional
$order["trackings"][1]["available_at"] = "2014-02-05T13:21:22+01:00"; // optional
$order["trackings"][1]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["trackings"][1]["address_line_1"] = "1600 Pennsylvania Avenue"; // optional
$order["trackings"][1]["address_line_2"] = "5º"; // optional
$order["trackings"][1]["postal_code"] = "08013"; // optional
$order["trackings"][1]["city"] = "Barcelona"; // optional
$order["trackings"][1]["state"] = "Barcelona"; // optional
$order["trackings"][1]["country_code"] = "ES"; // optional
$order["trackings"][2] = array();
$order["trackings"][2]["type"] = "postal";
$order["trackings"][2]["reference"] = "third";
$order["trackings"][2]["carrier"] = "SEUR";
$order["trackings"][2]["tracking_number"] = "TX123"; // optional
$order["trackings"][2]["tracking_url"] = "https://logistics.es/TX123"; // optional
$order["trackings"][2]["delivered_at"] = "2014-02-05T19:21:22+01:00"; // optional
$order["delivery_method"] = array();
$order["delivery_method"]["name"] = "SEUR24";
$order["delivery_method"]["days"] = "¡Entrega día siguiente!"; // optional
$order["delivery_method"]["provider"] = "Correos"; // optional
$order["delivery_method"]["home_delivery"] = true; // optional
$order["delivery_address"] = array(); // Mandatory unless <i>addresses_may_be_missing</i> is used.
$order["delivery_address"]["given_names"] = "Maria José";
$order["delivery_address"]["surnames"] = "Barroso Rajoy";
$order["delivery_address"]["company"] = "";
$order["delivery_address"]["address_line_1"] = "C/ Aragó 383";
$order["delivery_address"]["address_line_2"] = "5º";
$order["delivery_address"]["postal_code"] = "08013";
$order["delivery_address"]["city"] = "Barcelona";
$order["delivery_address"]["country_code"] = "ES";
$order["delivery_address"]["phone"] = "933 033 033"; // optional
$order["delivery_address"]["mobile_phone"] = "615 615 615"; // optional
$order["delivery_address"]["state"] = "Barcelona"; // optional
$order["delivery_address"]["extra"] = "I'm home between 9 and 12."; // optional
$order["delivery_address"]["vat_number"] = "B12345"; // optional
$order["invoice_address"] = array(); // Mandatory unless <i>addresses_may_be_missing</i> is used.
$order["invoice_address"]["given_names"] = "Maria José";
$order["invoice_address"]["surnames"] = "Barroso Rajoy";
$order["invoice_address"]["company"] = "";
$order["invoice_address"]["address_line_1"] = "";
$order["invoice_address"]["address_line_2"] = "";
$order["invoice_address"]["postal_code"] = "";
$order["invoice_address"]["city"] = "";
$order["invoice_address"]["country_code"] = "ES";
$order["invoice_address"]["phone"] = "933 033 033"; // optional
$order["invoice_address"]["mobile_phone"] = "615 615 615"; // optional
$order["invoice_address"]["state"] = "Tarragona"; // optional
$order["invoice_address"]["extra"] = "I'm home between 9 and 12."; // optional
$order["invoice_address"]["vat_number"] = "B12345"; // optional
$order["customer"] = array();
$order["customer"]["given_names"] = "Maria José";
$order["customer"]["surnames"] = "Barroso Rajoy";
$order["customer"]["title"] = "mr"; // optional
$order["customer"]["email"] = "nisse@example.com";
$order["customer"]["logged_in"] = true;
$order["customer"]["language_code"] = "es-ES";
$order["customer"]["ip_number"] = "12.23.34.45";
$order["customer"]["user_agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_0) AppleWebKit/537.36";
$order["customer"]["ref"] = 123; // optional
$order["customer"]["date_of_birth"] = "1980-01-20"; // optional
$order["customer"]["nin"] = "13003009L"; // optional
$order["customer"]["company"] = ""; // optional
$order["customer"]["vat_number"] = "B12345"; // optional
$order["customer"]["created_at"] = "2013-08-15T21:07:37+01:00"; // optional
$order["customer"]["updated_at"] = "2013-09-27T16:50:25+01:00"; // optional
$order["customer"]["rating"] = 100; // optional
$order["customer"]["nin_control"] = "15012018F2"; // optional
$order["customer"]["previous_orders"] = array(); // optional
$order["customer"]["previous_orders"][0] = array();
$order["customer"]["previous_orders"][0]["created_at"] = "2013-06-11T12:27:40+02:00";
$order["customer"]["previous_orders"][0]["amount"] = 4656;
$order["customer"]["previous_orders"][0]["currency"] = "EUR";
$order["customer"]["previous_orders"][0]["raw_status"] = "Shipped"; // optional
$order["customer"]["previous_orders"][0]["status"] = "shipped"; // optional
$order["customer"]["previous_orders"][0]["payment_method_raw"] = "PayPal"; // optional
$order["customer"]["previous_orders"][0]["payment_method"] = "PP"; // optional
$order["customer"]["previous_orders"][0]["postal_code"] = "08013"; // optional
$order["customer"]["previous_orders"][0]["country_code"] = "ES"; // optional
// $order["customer"]["vehicle"] = array(); // contract
$order["customer"]["vehicle"]["plaque"] = "0000AAA";
$order["customer"]["vehicle"]["brand"] = "Volkswagen"; // optional
$order["customer"]["vehicle"]["model"] = "Beetle"; // optional
$order["customer"]["vehicle"]["frame"] = "VF1RFD00653635032"; // optional
$order["customer"]["vehicle"]["first_registration_date"] = "2000-03-25"; // optional
// $order["instore"] = array(); // contract
$order["instore"]["code"] = "8324";
$order["gui"] = array();
$order["gui"]["layout"] = "desktop";
$order["platform"] = array();
$order["platform"]["name"] = "REPLACE WITH CORRECT VALUE BEFORE QA";
$order["platform"]["version"] = "REPLACE WITH CORRECT VALUE BEFORE QA";
$order["platform"]["plugin_version"] = "REPLACE WITH CORRECT VALUE BEFORE QA"; // optional
$order["platform"]["uname"] = "REPLACE WITH CORRECT VALUE BEFORE QA";
$order["platform"]["db_name"] = "REPLACE WITH CORRECT VALUE BEFORE QA";
$order["platform"]["db_version"] = "REPLACE WITH CORRECT VALUE BEFORE QA";
$order["platform"]["php_version"] = "REPLACE WITH CORRECT VALUE BEFORE QA"; // optional
$order["first_charge_date"] = "2001-01-01"; // optional
$order["subscription"] = array(); // optional
$order["subscription"]["cart"] = array(); // optional
$order["subscription"]["cart"]["currency"] = "EUR";
$order["subscription"]["cart"]["items"] = array();
$order["subscription"]["cart"]["items"][0] = array();
$order["subscription"]["cart"]["items"][0]["type"] = "product";
$order["subscription"]["cart"]["items"][0]["unique_reference"] = "12-123-1234";
$order["subscription"]["cart"]["items"][0]["catalogue_reference"] = "IPHONE12BLACK"; // optional
$order["subscription"]["cart"]["items"][0]["name"] = "Leather Case (iPod nano) - Negro / Chocolate";
$order["subscription"]["cart"]["items"][0]["monthly_price_with_tax"] = 3030;
$order["subscription"]["cart"]["items"][0]["vat_rate"] = 2100;
$order["subscription"]["cart"]["items"][0]["minimum_period"] = 24;
$order["subscription"]["cart"]["items"][0]["extension_period"] = 3;
$order["subscription"]["cart"]["items"][0]["start_on"] = "2013-10-18"; // optional
$order["subscription"]["cart"]["items"][0]["end_on"] = "2015-10-18"; // optional
$order["subscription"]["cart"]["items"][0]["extra"] = array(); // optional
$order["subscription"]["cart"]["items"][1] = array();
$order["subscription"]["cart"]["items"][1]["type"] = "subscriber_fee";
$order["subscription"]["cart"]["items"][1]["unique_reference"] = "12-123-1234";
$order["subscription"]["cart"]["items"][1]["catalogue_reference"] = "IPHONE12BLACK"; // optional
$order["subscription"]["cart"]["items"][1]["name"] = "Leather Case (iPod nano) - Negro / Chocolate";
$order["subscription"]["cart"]["items"][1]["monthly_price_with_tax"] = 3030;
$order["subscription"]["cart"]["items"][1]["vat_rate"] = 2100;
$order["subscription"]["cart"]["items"][1]["minimum_period"] = 24;
$order["subscription"]["cart"]["items"][1]["extension_period"] = 3;
$order["subscription"]["cart"]["items"][1]["start_on"] = "2013-10-18"; // optional
$order["subscription"]["cart"]["items"][1]["end_on"] = "2015-10-18"; // optional
$order["subscription"]["cart"]["items"][1]["extra"] = array(); // optional
$order["subscription"]["discounts"] = array(); // optional
$order["subscription"]["discounts"][0] = array();
$order["subscription"]["discounts"][0]["type"] = ["percent", "amount"];
$order["subscription"]["discounts"][0]["unique_reference"] = "12-123-1234";
$order["subscription"]["discounts"][0]["promotion_reference"] = "three_month_half_off"; // optional
$order["subscription"]["discounts"][0]["amount"] = 5000;
$order["subscription"]["discounts"][0]["start_month"] = 1;
$order["subscription"]["discounts"][0]["period_in_months"] = 3;