Documentación técnica

Form API Integration

This API is recommended for webmasters who would like to implement a connection to our system in a quick manner.

Webmasters would need to develop an HTML based form with specific parameters and POST url as specified below to which the end customer / order information must be submitted.

As soon as an end customer submits the form on the webmaster website he/she will be presented with the Payin7 system where the order would be finalized and accepted/rejected.

After the operation has completed webmasters could use our background notification service to receive additional information of the status of the order.

Please note that sending the customer to the OK URL stated below only indicates that the Customer has not been rejected and Payin7 has received his payment successfully. It does NOT indicate that the order has been fully verified by Payin7 and may be pending other further verifications and approvals before the store would send the goods in an order.
Only when the order state changes to active should the implementing system consider the order as 'good for shipping' by the store. This state can be monitored with the background notification service described below.

If you would like to receive a separate URL where Payin7 sends the Customer if the order is / is not pending further notifications the INCONCLUSIVE URL should be used (if there are further verifications pending). This functionality is not enabled by default and should be requested by Payin7 in advance.

The URL to which the form must be submitted is: https://stores.payin7.com/formapi/submit:

<form action="https://stores.payin7.com/formapi/submit" method="post">


<!-- Configuration parameters -->

<input name="account_id" type="hidden" value="CFG_STORE_ACCOUNT_ID" />

<input name="signature" type="hidden" value="CFG_SIGNATURE" />

<input name="ok_url" type="hidden" value="CFG_URL_OK" />

<input name="nok_url" type="hidden" value="CFG_URL_NOK" />

<input name="inconclusive_url" type="hidden" value="CFG_URL_INCONCLUSIVE" />

<input name="cancelled_url" type="hidden" value="CFG_CANCELLED_URL" />

<input name="callback_url" type="hidden" value="CFG_CALLBACK_URL" />

<input name="return_redirect" type="hidden" value="CFG_RETURN_REDIRECT" />

<input name="locale_code" type="hidden" value="CFG_LOCALE_CODE" />

<input name="sandbox_mode" type="hidden" value="CFG_SANDBOX_MODE" />

<input name="store_data" type="hidden" value="CUSTOM_STORE_DATA" />


<!-- Order details -->

<input name="order[id]" type="hidden" value="ORD_ORDER_ID" />

<input name="order[payment_method]" type="hidden" value="ORD_PAYMENT_METHOD" />

<input name="order[currency_code]" type="hidden" value="ORD_CURRENCY_CODE" />

<input name="order[shipping_method_code]" type="hidden" value="ORD_SHIPPING_METHOD_CODE" />

<input name="order[shipping_method_title]" type="hidden" value="ORD_SHIPPING_METHOD_TITLE" />

<input name="order[subtotal_with_tax]" type="hidden" value="ORD_SUBTOTAL_WITH_TAX" />

<input name="order[subtotal]" type="hidden" value="ORD_SUBTOTAL" />

<input name="order[tax]" type="hidden" value="ORD_TAX" />

<input name="order[shipping_with_tax]" type="hidden" value="ORD_SHIPPING_WITH_TAX" />

<input name="order[shipping]" type="hidden" value="ORD_SHIPPING" />

<input name="order[discount]" type="hidden" value="ORD_DISCOUNT" />

<input name="order[shipping_discount]" type="hidden" value="ORD_SHIPPING_DISCOUNT" />

<input name="order[total]" type="hidden" value="ORD_TOTAL" />

<input name="order[total_items]" type="hidden" value="ORD_TOTAL_ITEMS" />


<!-- Item details -->

<input name="items[n][item_id]" type="hidden" value="ITM_ITEM_ID" />

<input name="items[n][product_id]" type="hidden" value="ITM_PRODUCT_ID" />

<input name="items[n][name]" type="hidden" value="ITM_NAME" />

<input name="items[n][url]" type="hidden" value="ITM_URL" />

<input name="items[n][details]" type="hidden" value="ITM_DETAILS" />

<input name="items[n][details_full]" type="hidden" value="ITM_DETAILS_FULL" />

<input name="items[n][sku]" type="hidden" value="ITM_SKU" />

<input name="items[n][image_url]" type="hidden" value="ITM_IMAGE_URL" />

<input name="items[n][virtual]" type="hidden" value="ITM_VIRTUAL" />

<input name="items[n][quantity]" type="hidden" value="ITM_QUANTITY" />

<input name="items[n][quantity_decimal]" type="hidden" value="ITM_QUANTITY_DECIMAL" />

<input name="items[n][item_subtotal_with_tax]" type="hidden" value="ITM_SUBTOTAL_WITH_TAX" />

<input name="items[n][item_subtotal]" type="hidden" value="ITM_SUBTOTAL" />

<input name="items[n][item_tax]" type="hidden" value="ITM_TAX" />

<input name="items[n][item_tax_rate]" type="hidden" value="ITM_TAX_RATE" />

<input name="items[n][item_tax_before_discount]" type="hidden" value="ITM_TAX_BEFORE_DISCOUNT" />

<input name="items[n][item_shipping_with_tax]" type="hidden" value="ITM_SHIPPING_WITH_TAX" />

<input name="items[n][item_shipping]" type="hidden" value="ITM_SHIPPING" />

<input name="items[n][item_total_before_discount]" type="hidden" value="ITM_TOTAL_BEFORE_DISCOUNT" />

<input name="items[n][item_discount]" type="hidden" value="ITM_DISCOUNT" />

<input name="items[n][item_discount_with_tax]" type="hidden" value="ITM_DISCOUNT_WITH_TAX" />

<input name="items[n][item_total]" type="hidden" value="ITM_TOTAL" />

<input name="items[n][item_total_with_tax]" type="hidden" value="ITM_TOTAL_WITH_TAX" />


<!-- Customer details -->

<input name="customer[id]" type="hidden" value="CUST_CUSTOMER_ID" />

<input name="customer[guest]" type="hidden" value="CUST_IS_GUEST" />

<input name="customer[username]" type="hidden" value="CUST_USERNAME" />

<input name="customer[created_on]" type="hidden" value="CUST_CREATED_ON" />

<input name="customer[locale_code]" type="hidden" value="CUST_LOCALE_CODE" />

<input name="customer[birthdate]" type="hidden" value="CUST_BIRTHDATE" />

<input name="customer[email]" type="hidden" value="CUST_EMAIL" />

<input name="customer[title]" type="hidden" value="CUST_TITLE" />

<input name="customer[prefix]" type="hidden" value="CUST_PREFIX" />

<input name="customer[suffix]" type="hidden" value="CUST_SUFFIX" />

<input name="customer[first_name]" type="hidden" value="CUST_FIRST_NAME" />

<input name="customer[middle_name]" type="hidden" value="CUST_MIDDLE_NAME" />

<input name="customer[last_name]" type="hidden" value="CUST_LAST_NAME" />

<input name="customer[company_name]" type="hidden" value="CUST_COMPANY_NAME" />

<input name="customer[gender]" type="hidden" value="CUST_GENDER" />

<input name="customer[telephone1]" type="hidden" value="CUST_TELEPHONE1" />

<input name="customer[telephone2]" type="hidden" value="CUST_TELEPHONE2" />

<input name="customer[telephone3]" type="hidden" value="CUST_TELEPHONE3" />

<input name="customer[fax]" type="hidden" value="CUST_FAX" />

<input name="customer[vat_number]" type="hidden" value="CUST_VAT_NUMBER" />

<input name="customer[document_number]" type="hidden" value="CUST_DOCUMENT_NUMBER" />

<input name="customer[document_type]" type="hidden" value="CUST_DOCUMENT_TYPE" />


<!-- Customer details -->

<input name="addresses[n][id]" type="hidden" value="ADR_ADDRESS_ID" />

<input name="addresses[n][type]" type="hidden" value="ADR_TYPE" />

<input name="addresses[n][title]" type="hidden" value="ADR_TITLE" />

<input name="addresses[n][prefix]" type="hidden" value="ADR_PREFIX" />

<input name="addresses[n][suffix]" type="hidden" value="ADR_SUFFIX" />

<input name="addresses[n][first_name]" type="hidden" value="ADR_FIRST_NAME" />

<input name="addresses[n][middle_name]" type="hidden" value="ADR_MIDDLE_NAME" />

<input name="addresses[n][last_name]" type="hidden" value="ADR_LAST_NAME" />

<input name="addresses[n][company_name]" type="hidden" value="ADR_COMPANY_NAME" />

<input name="addresses[n][street_address_1]" type="hidden" value="ADR_STREET_ADDRESS1" />

<input name="addresses[n][street_address_2]" type="hidden" value="ADR_STREET_ADDRESS2" />

<input name="addresses[n][street_address_3]" type="hidden" value="ADR_STREET_ADDRESS3" />

<input name="addresses[n][street_address_4]" type="hidden" value="ADR_STREET_ADDRESS4" />

<input name="addresses[n][city]" type="hidden" value="ADR_ADDRESS_CITY" />

<input name="addresses[n][country_code]" type="hidden" value="ADR_ADDRESS_COUNTRY_CODE" />

<input name="addresses[n][state]" type="hidden" value="ADR_ADDRESS_STATE" />

<input name="addresses[n][region]" type="hidden" value="ADR_ADDRESS_REGION" />

<input name="addresses[n][region_code]" type="hidden" value="ADR_ADDRESS_REGION_CODE" />

<input name="addresses[n][zip_code]" type="hidden" value="ADR_ADDRESS_ZIP_CODE" />

<input name="addresses[n][telephone1]" type="hidden" value="ADR_TELEPHONE1" />

<input name="addresses[n][telephone2]" type="hidden" value="ADR_TELEPHONE2" />

<input name="addresses[n][telephone3]" type="hidden" value="ADR_TELEPHONE3" />

<input name="addresses[n][fax]" type="hidden" value="ADR_FAX" />

<input name="addresses[n][vat_number]" type="hidden" value="ADR_VAT_NUMBER" />



<!-- Optional submission button -->
<input type="submit" value="Complete Order"/>

</form>

Here is an explanation of what each field code specified in input is used for. It is also indicated which is required and which is optional:

  • Configuration parameters
  • Name
  • Type
  • Description
  • Example
  • CFG_STORE_ACCOUNT_ID
  • required
  • Account ID as provided by Payin7
  • STOR-123
  • CFG_SIGNATURE
  • required
  • Verification signature used to authorize the request. Read further below the parameters table to understand how it should be generated.
  • CFG_URL_OK
  • required
  • URL to which the customer should be returned upon a successful order.
  • /order_success
  • CFG_URL_NOK
  • optional
  • URL to which the customer should be returned upon a failed order. If not specified the CFG_URL_OK will be used.
  • /order_failure
  • CFG_URL_INCONCLUSIVE
  • optional
  • URL to which the customer should be returned if there are further verifications which Payin7 must do before it is fully accepted (but it has been initially approved and paid successfully).Note that this functionality / url is not enabled by default and should be requested from Payin7 in advance. If this functionality is not enabled the OK URL is used for both OK and INCONCLUSIVE responses.
  • /order_inconclusive
  • CFG_CANCELLED_URL
  • optional
  • URL to which the customer should be returned upon cancelling the order. If not specified the CFG_URL_NOK will be used.
  • /order_cancelled
  • CFG_CALLBACK_URL
  • optional
  • URL to which Payin7 should send notifications regarding the order. Read below the parameters table for format of the responses sent.
  • /order_callback
  • CFG_RETURN_REDIRECT
  • optional
  • If set to '1' Payin7 will be forced to redirect back to the store instead of POST-ing the data. In this scenario we will return only the order state with var name 'order_state' in the URL query params
  • 1
  • CFG_LOCALE_CODE
  • required
  • ISO Locale code which was used by the Customer at the moment of making the order
  • en_US
  • CFG_SANDBOX_MODE
  • optional
  • If set to '1' the order will be created in test/sandbox mode and it will involve no real payment.
  • 1
  • CUSTOM_STORE_DATA
  • optional
  • Custom store data which will be posted back to the store in the OK/NOK/CANCELLED urls
  • Order details
  • ORD_ORDER_ID
  • required
  • Unique order id to be used for identifying the order for the store. It must be different for all order submissions.
  • 123444
  • ORD_PAYMENT_METHOD
  • required
  • Payment method (installments, seven_days)
  • installments
  • ORD_CURRENCY_CODE
  • required
  • Currency code of the order
  • EUR
  • ORD_SHIPPING_METHOD_CODE
  • optional
  • Code of the used shipping method
  • DHL
  • ORD_SHIPPING_METHOD_TITLE
  • optional
  • Title of the used shipping method
  • DHL Service
  • ORD_SUBTOTAL_WITH_TAX
  • required
  • Subtotal of the entire order including the tax amount
  • 110
  • ORD_SUBTOTAL
  • required
  • Subtotal of the entire order
  • 100
  • ORD_TAX
  • optional
  • Tax / VAT amount
  • 10
  • ORD_SHIPPING_WITH_TAX
  • optional
  • Shipping amount with shipping tax included
  • 35
  • ORD_SHIPPING
  • optional
  • Shipping amount
  • 30
  • ORD_DISCOUNT
  • optional
  • Order discount if applied
  • 5
  • ORD_SHIPPING_DISCOUNT
  • optional
  • Shipping discount if applied
  • 2
  • ORD_TOTAL
  • required
  • Total amount of order (items + shipping + taxes)
  • 150
  • ORD_TOTAL_ITEMS
  • required
  • Total number of unique item positions in the order
  • 2
  • Item details
  • ITM_ITEM_ID
  • required
  • Unique item id
  • 11223344
  • ITM_PRODUCT_ID
  • required
  • Internal store item id if applicable
  • 11223344
  • ITM_NAME
  • required
  • Item name
  • Basketball
  • ITM_URL
  • required
  • Webpage of the item
  • ITM_DETAILS
  • required
  • Short item details (base64 encoded HTML accepted)
  • ITM_DETAILS_FULL
  • optional
  • Full item details (base64 encoded HTML accepted)
  • ITM_SKU
  • optional
  • Item SKU
  • BASKETBALL-1
  • ITM_IMAGE_URL
  • required
  • URL of the item's image
  • ITM_VIRTUAL
  • optional
  • If the item is a virtual merchandise (does not exist as a physical item) specify '1'
  • 1
  • ITM_QUANTITY
  • required
  • Purchased quantity
  • 20
  • ITM_QUANTITY_DECIMAL
  • optional
  • If the item quantity is not a whole number specify '1'
  • 0
  • ITM_SUBTOTAL_WITH_TAX
  • required
  • Total amount with tax included
  • ITM_SUBTOTAL
  • required
  • Subtotal amount
  • ITM_TAX
  • optional
  • Tax amount
  • ITM_TAX_RATE
  • required
  • Tax rate (VAT %)
  • 20%
  • ITM_TAX_BEFORE_DISCOUNT
  • optional
  • Tax amount before discount
  • ITM_SHIPPING_WITH_TAX
  • optional
  • Shipping amount with tax
  • ITM_SHIPPING
  • optional
  • Shipping amount
  • ITM_TOTAL_BEFORE_DISCOUNT
  • required
  • Total amount before discount
  • ITM_DISCOUNT
  • optional
  • Discount amount
  • ITM_DISCOUNT_WITH_TAX
  • optional
  • Discount amount with tax
  • ITM_TOTAL
  • required
  • Total amount
  • ITM_TOTAL_WITH_TAX
  • required
  • Total amount with tax
  • Customer details
  • CUST_CUSTOMER_ID
  • optional
  • Unique customer ID
  • CUST_IS_GUEST
  • optional
  • If the customer is not a registered member of the website - specify '1'
  • 1
  • CUST_USERNAME
  • optional
  • Username of the customer if a registered member
  • miracle_bg
  • CUST_CREATED_ON
  • optional
  • Date/time when the customer had been registered in the website
  • CUST_LOCALE_CODE
  • optional
  • Preferred locale code of the customer
  • en_US
  • CUST_BIRTHDATE
  • required
  • Customer birthdate
  • 1982-03-18
  • CUST_TITLE
  • optional
  • Customer Title
  • Mr.
  • CUST_PREFIX
  • optional
  • Customer prefix name
  • CUST_SUFFIX
  • optional
  • Customer suffix name
  • CUST_FIRST_NAME
  • required
  • Customer first name
  • Martin
  • CUST_MIDDLE_NAME
  • optional
  • Customer middle name
  • Nikolov
  • CUST_LAST_NAME
  • required
  • Customer last name
  • Kovachev
  • CUST_COMPANY_NAME
  • optional
  • Customer company name
  • Payin7 S.L.
  • CUST_GENDER
  • optional
  • Customer gender (male/female)
  • male
  • CUST_TELEPHONE1
  • required
  • Customer telephone 1 (with code)
  • +34911223344
  • CUST_TELEPHONE2
  • optional
  • Customer telephone 2 (with code)
  • +34911223344
  • CUST_TELEPHONE3
  • optional
  • Customer telephone 3 (with code)
  • +34911223344
  • CUST_FAX
  • optional
  • Customer fax number (with code)
  • +34911223344
  • CUST_VAT_NUMBER
  • required
  • Customer VAT number
  • ES1233332233
  • CUST_DOCUMENT_NUMBER
  • required
  • Customer document identification number
  • CUST_DOCUMENT_TYPE
  • optional
  • Customer identification document type (NIF/CIF/other)
  • nif
  • Customer details
  • ADR_ADDRESS_ID
  • optional
  • Unique address ID
  • ADR_TYPE
  • required
  • Address type (shipping/billing)
  • shipping
  • ADR_TITLE
  • optional
  • Title of the address
  • ADR_PREFIX
  • optional
  • Address prefix name
  • ADR_SUFFIX
  • optional
  • Address suffix name
  • ADR_FIRST_NAME
  • required
  • Customer first name
  • ADR_MIDDLE_NAME
  • optional
  • Customer middle name
  • ADR_LAST_NAME
  • required
  • Customer last name
  • ADR_COMPANY_NAME
  • optional
  • Customer company name
  • ADR_STREET_ADDRESS1
  • required
  • Address line 1
  • ADR_STREET_ADDRESS2
  • optional
  • Address line 2
  • ADR_STREET_ADDRESS3
  • optional
  • Address line 3
  • ADR_STREET_ADDRESS4
  • optional
  • Address line 4
  • ADR_ADDRESS_CITY
  • required
  • Customer city
  • ADR_ADDRESS_COUNTRY_CODE
  • required
  • Customer country code (ISO code)
  • ES
  • ADR_ADDRESS_STATE
  • optional
  • Customer state name
  • ADR_ADDRESS_REGION
  • optional
  • Customer region
  • ADR_ADDRESS_REGION_CODE
  • optional
  • Customer region code
  • ADR_ADDRESS_ZIP_CODE
  • required
  • Customer ZIP code
  • ADR_TELEPHONE1
  • required
  • Customer phone number 1 (with code)
  • ADR_TELEPHONE2
  • optional
  • Customer phone number 2 (with code)
  • ADR_TELEPHONE3
  • optional
  • Customer phone number 3 (with code)
  • ADR_FAX
  • optional
  • Customer fax number (with code)
  • ADR_VAT_NUMBER
  • required
  • Customer VAT number
 

Notes

- Use the symbol . (dot) to indicate decimal place in an amount/price.

- Date/Times are to be specified in the ISO8601 format: YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

Signature code generation

The signature parameter must be generating by concatenating the following parameters and then applying SHA1 over the combined string:

    SIGNATURE_KEY (provided by Payin7) + CFG_STORE_ACCOUNT_ID + ORD_ORDER_ID + ORD_TOTAL

Status Responses (to OK / NOK / INCONCLUSIVE urls):

Payin7 will send the following POST data to the OK / NOK / INCONCLUSIVE urls:

  • order_id: (STRING): GUID like unique order identifier
  • order_state: (STRING): Represents the current state of the order. Possible types are listed below.
  • signature2: (STRING): Code which may be used optionally to verify the integrity of the response data.
  • order_total_items: (INT): Total number of items in the order.
  • order_total: (DECIMAL): Grand total amount of the order.
  • store_data: (STRING): Store data as submitted initially with the form field: CUSTOM_STORE_DATA.

The signature2 parameter is generated by concatenating the following parameters and then applying SHA1 over the combined string:

    SIGNATURE_KEY (provided by Payin7) + CFG_STORE_ACCOUNT_ID + ORDER_ID + ORDER_TOTAL + ORDER_TOTAL_ITEMS

Callback Notifications

Payin7 can optionally send asynchronous background notifications to your system upon significant events - for example - when a submitted order is accepted, rejected or cancelled.

The system will retry sending each notification up to 3 times - each one a minute apart (the first sent immediately after the event) after which it will be marked as failed. A failed submission is recognized by the receiver not sending the HTTP 200 OK code in the response.

You may additionally use the signature2 field which is sent with every response to verify the validity of the message sent by us.

The signature parameter is generated by concatenating the following parameters and then applying SHA1 over the combined string:

    SIGNATURE_KEY (provided by Payin7) + CFG_STORE_ACCOUNT_ID + ORDER_ID + ORDER_TOTAL + ORDER_TOTAL_ITEMS

Notification ORDER_STATE_CHANGE

  {
"id":"unique_notification_id",
"generated_at":"2016-05-04T12:41:45.000+02:00",
"signature2":"CFG_SIGNATURE",
"order_id":"28F6484A-966D-43EE-84AC-5629CCA1E11E-4602D02B-B430-4700-A392-E50D56DDA23B",
"order_total_items":"3",
"order_total":"50.4422",
"store_data":"CUSTOM_STORE_DATA",
"error_code":null,
"error_message":null,
"description":"Faded Short Sleeves T-shirt (1)",
"order_state":"active"
}

Possible Submission Errors

  • Code 2010: Store account not found.
  • Code 2011: Store account is disabled.
  • Code 2012: Form submission is disabled.
  • Code 2013: Form signature is invalid.

Possible Order States

  • ordered: Order has been stored in the system and is pending processing.
  • accepted: Order data has been verified and is found to be valid.
  • verified: Customer has been verified and is allowed to make the order.
  • rejected: Customer has been rejected and will not be able to complete the order.
  • paid: Payment has been received successfully and order is pending additional customer verification (manual or automatic) before being activated.
  • active: Order has been accepted / paid for (first installment).
  • completed: All installments / Order has been paid in full.
  • cancelled: Order has been cancelled.
  • errorous: Order data is errorous and is rejected.

Document Revisions

Rev 4 (10.02.2020):

- Updated the possible order states (PAID state added)
- Added a new callback url to send the customer back to an URL when the order is successfully collected but verification by the Payin7 system/staff is pending.

Rev 3 (16.07.2019):

- Signature verification for 'Status Responses (to OK/NOK urls) and Callback Notifications' has been updated. The new signature format is now 'SIGNATURE2'. SIGNATURE1 (SIGNATURE_KEY (provided by Payin7) + CFG_STORE_ACCOUNT_ID + ORDER_ID + ORDER_STATE + ORDER_TOTAL + ORDER_TOTAL_ITEMS) will be left functional for backward compatibility until further notice - but it MUST NOT be used for new installations!

Rev 2 (06.08.2018):

- Field ORD_SUBTITLE_WITH_TAX renamed to ORD_SUBTOTAL_WITH_TAX - Fields made required: ITM_SUBTOTAL_WITH_TAX, ITM_TOTAL_WITH_TAX, ITM_DETAILS, ITM_URL, ITM_IMAGE_URL, ORD_SUBTOTAL_WITH_TAX, ITM_TOTAL_BEFORE_DISCOUNT, CFG_LOCALE_CODE, CUST_DOCUMENT_NUMBER, ADR_TELEPHONE1, ADR_VAT_NUMBER, ITM_TAX_RATE

Rev 1 (25.10.2017):

- CUSTOM_STORE_DATA request param is moved into the 'CONFIGURATION PARAMETERS' section due to being put by mistake in the 'CUSTOMER DETAILS' section.
- Added new fields sent with POST to the OK/NOK/CANCEL urls:

  • order_id
  • order_state
  • signature
  • order_total_items
  • order_total
  • store_data

- Updated the response of the `ORDER_STATE_CHANGE` callback notification:

  • `order_status` field removed
  • `order_state` field added
  • `order_total_items` field added
  • `order_total` field added
  • `store_data` field added

- Added submission error codes which may be returned by the system upon submission.

- Added a list of possible order states.

- Background notifications are now being retried up to 3 times.



© Payin7 - 2021 | www.payin7.com