Reporting process for Mirakl Marketplace

  1. Smart2Pay generates a daily transactional report file for Mirakl. The transactional report file contains the following information:
    ID
    ID
    Definition
    The ID of the transaction in Smart2Pay system
    Type
    int
    : The ID of the transaction in Smart2Pay system;
    MerchantTransactionID
    MerchantTransactionID
    Definition
    Merchant Transaction ID, a number that uniquely identifies a transaction in your system.
    Type
    string
    : Merchant Transaction ID, a number that uniquely identifies a transaction in your system;
    OriginatorTransactionID
    OriginatorTransactionID
    Definition
    The ID of the transaction/refund in The Marketplace system
    Type
    string
    : The ID of the transaction/refund in The Marketplace system;

    InputDateTime
    InputDateTime
    Definition
    The date and time of inserting the transaction in Smart2Pay system
    Type
    datetime
    : The date and time of inserting the transaction in Smart2Pay system;

    PaymentStateDefID
    PaymentStateDefID
    Definition
    The ID of the payment status in Smart2Pay system. It can have the following values: 1 - Open, 2 - Success, 3 - Cancelled, 4 - Failed, 5 - Expired, 9 - Authorized, 11 - Captured.
    : The status id of the transaction in Smart2Pay system;

    Status
    Status
    Definition
    The description of the transaction status in the Smart2Pay system: Open (Pending), Success (not used for card payments), Cancelled, Failed, Expired, Authorized, Captured.
    : The description of the transaction status in the Smart2Pay system;

    MerchantAmount
    MerchantAmount
    Definition
    The amount of the transaction.
    Type
    float
    : The amount of the transaction;

    MerchantCurrency
    MerchantCurrency
    Definition
    The currency of the transaction. ISO 4217 format (e.g. EUR)
    : The currency of the transaction;

    CapturedAmount
    CapturedAmount
    Definition
    The amount that has been captured. Float with 2 decimals (e.g. 33.99)
    Type
    float
    : The amount that has been captured;

    MethodID
    MethodID
    Definition
    The ID of the payment methods used. For credit cards payments the ID is 6.
    Type
    int
    : The ID of the payment methods used. For credit cards payments this is 6.;

    MethodName
    MethodName
    Definition
    The name of the payment method used: SmartCards.
    : The name of the payment method used.;

    ReportedByBOTOperatorDate
    ReportedByBOTOperatorDate
    Definition
    The date when the transaction was exported to CSV file.
    Type
    datetime
    : The date when the transaction was exported to csv file;

    SpecificDetails
    SpecificDetails
    Definition
    Specific Details
    : Not used;

    ReconciliationProviderID
    ReconciliationProviderID
    Definition
    The ID that appears on the bank statement of the customer (usually same as RootProviderTransactionID).
    Type
    string
    : ID appearing on the bank statement of the customer (usually same as RootProviderTransactionID);

    ProviderTransactionID
    ProviderTransactionID
    Definition
    Provider Transaction ID
    : Not used for card payments;

    MerchantAlias
    MerchantAlias
    Definition
    The name of the Shop.
    Type
    string
    : Shop Name;

    RootProviderTransactionID
    RootProviderTransactionID
    Definition
    The ID of the payment in acquiring system.
    Type
    string
    : ID of the payment in acquiring system;

    Country
    Country
    Definition
    The country of the payer if available. ISO_3166-1_alpha-2 format. (e.g. IT).
    : The country of the payer if available.
  2.  

  3. Smart2Pay will generate a Settlement invoice report containing information at transaction level for each shop. The Settlement invoice report contains the following information:1 Settlement invoice report per shop
    GPaymentId
    GPaymentId
    Definition
    GPaymentId
    : Not used;
    PaymentId
    PaymentId
    Definition
    The ID of the payment in Smart2Pay system.
    Type
    int
    : PaymentID in Smart2Pay system;

    Type
    Type
    Definition
    Transaction Type. It can be type: Payment, Refund, Inquiry or Chargeback.
    Type
    string
    : Transaction Type. Can be Payment, Refund, Inquiry or Chargeback;

    PaymentMethodName
    PaymentMethodName
    Definition
    The name of the payment method used. E.g. SmartCards
    Type
    string
    : Name of the payment method used;

    CustomerName
    CustomerName
    Definition
    The name of the customer, if available.
    Type
    string
    : The name of the customer, if available;

    MerchantName
    MerchantName
    Definition
    The name of the merchant account.
    Type
    string
    : The name of the merchant account;

    MerchantID
    MerchantID
    Definition
    The ID of the transaction/refund in your system.
    Type
    string
    : The transaction/refund id in your system;

    GtId
    GtId
    Definition
    GtId
    : Not used;

    IssuerName
    IssuerName
    Definition
    Issuer Name
    : Not used;

    IdealTrxId
    IdealTrxId
    Definition
    IdealTrxId
    : Not used;

    Country
    Country
    Definition
    The country of the payer, if available. ISO_3166-1_alpha-2 format. (e.g. IT).
    : The country of the payer, if available;

    InputDateTime
    InputDateTime
    Definition
    The date and time of inserting the transaction in Smart2Pay system.
    Type
    datetime
    : The date and time of inserting the transaction in Smart2Pay system;

    Amount
    Amount
    Definition
    The amount of the transaction.
    Type
    float
    : The amount of the transaction;

    Currency
    Currency
    Definition
    The currency of the transaction. ISO 4217 format (e.g. EUR).
    : The currency of the transaction;

    Status
    Status
    Definition
    The description of the transaction status in the Smart2Pay system: Open (Pending), Success (not used for card payments), Cancelled, Failed, Authorized, Captured
    : The description of the transaction status in the Smart2Pay system;

    ExchangeRate
    ExchangeRate
    Definition
    The exchange rate if the transaction needs to be converted from transaction currency to the settlement currency.
    Type
    float
    : The exchange rate if the transaction needs to be converted from transaction currency to the settlement currency;

    CalculatedAmount
    CalculatedAmount
    Definition
    The transaction amount converted to the settlement currency.
    Type
    float
    : The transaction amount converted to the settlement currency;

    ReferenceCurrency
    ReferenceCurrency
    Definition
    The settlement currency.
    Type
    float
    : The settlement currency;

    TransactionFee
    TransactionFee
    Definition
    Gateway fee (if applies).
    Type
    float
    : Gateway fee (if applies);

    GeneralFee
    GeneralFee
    Definition
    Gateway fee (if applies)
    Type
    float
    : Gateway fee (if applies);

    AttemptFee
    AttemptFee
    Definition
    Gateway fee (per attempt, if applies).
    Type
    float
    : Gateway fee (per attempt, if applies);

    IssuedFee
    IssuedFee
    Definition
    Gateway fee (per acquiring bank/payment method provider attempt fee if applies).
    Type
    float
    : Gateway fee (per acquiring bank/payment method provider attempt fee if applies);

    LocalVatFee
    LocalVatFee
    Definition
    Local payment method VAT (if applies).
    Type
    float
    : Local payment method VAT (if applies);

    VAT
    VAT
    Definition
    Value added tax (if applies).
    Type
    float
    : Value added tax (if applies);

    Comission
    Comission
    Definition
    Commission of the marketplace/agent (if applies).
    Type
    float
    : Commission of the marketplace/agent (if applies);

    SiteID
    SiteID
    Definition
    The ID of the shop.
    Type
    int
    : ID of the shop;

    SiteAlias
    SiteAlias
    Definition
    Shop Alias.
    Type
    string
    : Shop Alias;

    OriginatorTransactionID
    OriginatorTransactionID
    Definition
    The ID of the transaction/refund in The Marketplace system.
    Type
    string
    : The ID of the transaction/refund in The Marketplace system.
  4.  

  5. Smart2Pay will also generate an aggregated Settlement invoice report containing information at transaction level for the Marketplace. Settlement of the commission will be based on this settlement invoice. Format is the same as in the Settlement invoice report above.

Below there are examples of Settlement invoice reports in all supported formats:

Settlement Flow for Mirakl Marketplace

Settlement cycles are defined in Smart2Pay system. Based on this, Smart2Pay generates settlement invoices for each shop. Also, Smart2Pay generates a commission settlement invoice for Mirakl Marketplace.

The acquiring banks and alternative payment method providers settle to Smart2Pay the (Gross amount – Acquiring/Processing Fees).

  • Smart2Pay settles gross amount – operator commission – acquiring fees to each shop. Settlement frequency: weekly.
  • Smart2Pay settles commission to Mirakl Marketplace based on Transaction Log API exposed by the Mirakl. Settlement frequency: weekly.

Optional functionalities:

  • Subscription fee can be collected by Smart2Pay from the shops on behalf of the marketplace operator.
  • Manual credits / debits will be issued by Mirakl Marketplace towards the shops and performed by Smart2Pay.
  • Mirakl Marketplace can withhold the payment of certain transactions towards the shop (e.g. only the transactions with PaymentStatus marked as PAID will be settled).

Reconciliation process for Mirakl Marketplace

Smart2Pay reconciles at transaction level with the acquiring banks and alternative method providers.

The SiteID / APIKEY will be used to initiate the transactions towards Smart2Pay. The Mirakl Marketplace Transaction ID needs to be submitted by Smart2Pay REST API in the OriginatorTransactionID field for reporting and reconciliation purposes towards the shops / Mirakl Marketplace.

Transactional Flow for Mirakl Marketplace

Orders containing items from multiple shops will be sent for authorization in multiple transactions, each transaction containing items for a single shop.

Credit card transactions are authorized and their status is communicated on the following route: Acquirer -> Smart2Pay -> Mirakl Marketplace.

Transactions are manually captured within 7 days from authorization.

Tokenization, 3D and fraud prevention solutions are available upon request. For more information visit: Credit Card Payments.

Alternative payment methods are authorized and captured in one step and their status is communicated on the following route: Payment method provider -> Smart2Pay -> Mirakl Marketplace.

You need to integrate our REST API described here: https://docs.smart2pay.com.

Mirakl’s Pre-Settlement Transaction API

Mirakl Marketplace exposes a Transaction Log API based on which Smart2Pay settles commissions for. Information about all the transactions created or updated within a certain interval can be retrieved by using an action based on GET HTTP request. The response will contain a transaction list in JSON format that returns all the transactions that were created or updated in the interval start_date – end_date.

Only a limited amount of details for each transaction will be provided.

Definition: GET /api/transactions_logs?shop_id=…&start_date=…&end_date=…&start_transaction_date=…&e
nd_transaction_date=…&updated_since=…&payment_voucher=…&payment_states=…&transactio
n_types=…&paginate=…&accounting_document_number=…&order_ids=…&order_line_ids=…

Where:
  • shop_id – [optional] shop id for filtering;
  • start_date – [optional] creation date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • end_date – [optional] creation date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • start_transaction_date – [optional] transaction date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • end_transaction_date – [optional] transaction date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • updated_since – [optional] last updated date for filtering. Format: “yyyy-MM-dd’T’HH:mm:ss”;
  • payment_voucher – [optional] payment voucher number for filtering;
  • payment_states – [optional] payment states separated by comma for filtering;
  • transaction_types – [optional] transaction types separated by comma for filtering;
  • paginate – [optional] Control the pagination usage. Default: true;
  • accounting_document_number – [optional] an accounting document number for filtering (invoice or credit note number);
  • order_ids – [optional] order id list for filtering, using comma (,) as a separator;
  • order_line_ids – [optional] order line id list for filtering, using comma (,) as a separator.

Request Model:

GET /v1/transactions?{start_date}&{end_date}
Authorization: Basic Pre-shared-APIKEY

Response Model:

{
  "lines": [
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 1.03,
      "balance": 1433.14,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 45,
      "offer_sku": "sku-AT5",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-2",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa8",
      "product_title": "Women's Retro Romance 3 Compartment Shopper",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": "TAXDEFAULT",
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "COMMISSION_VAT",
      "vat_rate": 20
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 5.17,
      "balance": 1434.17,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 45,
      "offer_sku": "sku-AT5",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-2",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa8",
      "product_title": "Women's Retro Romance 3 Compartment Shopper",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "COMMISSION_FEE",
      "vat_rate": 20
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 2,
      "amount_debited": 0,
      "balance": 1439.34,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 45,
      "offer_sku": "sku-AT5",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-2",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa8",
      "product_title": "Women's Retro Romance 3 Compartment Shopper",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": null,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "ORDER_SHIPPING_AMOUNT",
      "vat_rate": null
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 45,
      "amount_debited": 0,
      "balance": 1437.34,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 45,
      "offer_sku": "sku-AT5",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-2",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa8",
      "product_title": "Women's Retro Romance 3 Compartment Shopper",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": null,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "ORDER_AMOUNT",
      "vat_rate": null
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 1.58,
      "balance": 1392.34,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 67,
      "offer_sku": "sku-AT14",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa27",
      "product_title": "Black Label Relaxed Fit Jeans",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": "TAXDEFAULT",
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "COMMISSION_VAT",
      "vat_rate": 20
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 7.92,
      "balance": 1393.92,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 67,
      "offer_sku": "sku-AT14",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa27",
      "product_title": "Black Label Relaxed Fit Jeans",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "COMMISSION_FEE",
      "vat_rate": 20
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 5,
      "amount_debited": 0,
      "balance": 1401.84,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 67,
      "offer_sku": "sku-AT14",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa27",
      "product_title": "Black Label Relaxed Fit Jeans",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": null,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "ORDER_SHIPPING_AMOUNT",
      "vat_rate": null
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 67,
      "amount_debited": 0,
      "balance": 1396.84,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Premium sellers Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:09Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:30:00Z",
      "offer_price_unit": 67,
      "offer_sku": "sku-AT14",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-A",
      "order_line_id": "1443191231271-A-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "sku-fa27",
      "product_title": "Black Label Relaxed Fit Jeans",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2012,
      "shop_name": "Everything Store",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": null,
      "transaction_date": "2015-09-25T14:28:06Z",
      "transaction_number": "1443191231271-A-999-999",
      "transaction_type": "ORDER_AMOUNT",
      "vat_rate": null
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 1.43,
      "balance": 57.27,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Default Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:03Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:15:00Z",
      "offer_price_unit": 59.99,
      "offer_sku": "S2044",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-B",
      "order_line_id": "1443191231271-B-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "CLP_01",
      "product_title": "Dress for tennis players",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2041,
      "shop_name": "FONQ_SHOP TEST",
      "shop_operator_internal_id": null,
      "shop_tax_code": "TAXDEFAULT",
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:27:59Z",
      "transaction_number": "1443191231271-B-999-999",
      "transaction_type": "COMMISSION_VAT",
      "vat_rate": 20
    },
    {
      "accounting_document_creation_date": null,
      "accounting_document_number": null,
      "amount_credited": 0,
      "amount_debited": 7.15,
      "balance": 58.7,
      "category_code": "MOD",
      "category_label": "Clothing & Accessories",
      "commission_grid_label": "Default Grid",
      "currency_iso_code": "USD",
      "date_created": "2015-09-25T14:28:03Z",
      "invoice_creation_date": null,
      "invoice_number": null,
      "last_updated": "2015-09-25T18:15:00Z",
      "offer_price_unit": 59.99,
      "offer_sku": "S2044",
      "offer_state": "11",
      "order_commercial_id": "1443191231271",
      "order_id": "1443191231271-B",
      "order_line_id": "1443191231271-B-1",
      "order_state": "RECEIVED",
      "order_tax_code": null,
      "payment_state": "PAYABLE",
      "payment_voucher_number": null,
      "product_sku": "CLP_01",
      "product_title": "Dress for tennis players",
      "quantity": 1,
      "refund_id": null,
      "shipping_type_code": "INIT",
      "shipping_zone_code": "INIT",
      "shop_id": 2041,
      "shop_name": "FONQ_SHOP TEST",
      "shop_operator_internal_id": null,
      "shop_tax_code": null,
      "shop_tax_rate": 20,
      "transaction_date": "2015-09-25T14:27:59Z",
      "transaction_number": "1443191231271-B-999-999",
      "transaction_type": "COMMISSION_FEE",
      "vat_rate": 20
    }
  ],
  "total_count": 4545
}

The transaction_type field contains the following information:

  • COMMISSION_VAT
  • COMMISSION_FEE
  • ORDER_SHIPPING_AMOUNT
  • ORDER_AMOUNT
  • MANUAL_CREDIT
  • MANUAL_CREDIT_VAT
  • ORDER_AMOUNT_TAX
  • ORDER_SHIPPING_AMOUNT_TAX
  • REFUND_ORDER_AMOUNT
  • REFUND_ORDER_SHIPPING_AMOUNT
  • REFUND_COMMISSION_FEE
  • REFUND_COMMISSION_VAT
  • REFUND_ORDER_AMOUNT_TAX
  • REFUND_ORDER_SHIPPING_AMOUNT_TAX
  • SUBSCRIPTION_FEE
  • SUBSCRIPTION_VAT

Only the transactions with payment_state = “PAID” will be settled in the current settlement cycle.

Mirakl Notification for Shop Approval

Whenever a shop is approved in Smart2Pay onboarding system, a notification is sent from Smart2Pay to Mirakl Marketplace where the following info is send, and whether it was successful or not.

Mirakl Marketplace needs to respond with HTTP return code 204 (No Content) otherwise the approval will be resubmitted!

Definition: POST /api/shop/{ID}/notification

Where:
  • {ID} – ID of the shop

Shop Approval Notification Format:

{
    "merchant_site": {
        "shop_id": Int,
        "site_id": Int (eg. 31261),
        "api_key": "SmasdsPx6n2KJU9MNKcBdlqdLJZOXSl9IA/kdksjSsdDWD",
        "created": "Date (yyyy-mm-dd hh:mm:ss, eg. 2018-12-31 23:59:59)",
        "url": "http://www.johnshop.it",
    }
}

Response:

204 No Content

We recommend you to always verify the Notification content we sent and not just simply/automatically respond to our notifications.

In exceptional cases it is possible to receive duplicate notifications and your system should be able to handle such situations.

If you do not respond to the notifications of type Approval or our system will keep sending the notifications until it receives a response. At first you will be notified more often. Once the time passes the notifications from our system will be rare and they will eventually stop (after a period of time defined in our system, currently set to 7 days).

Get the List of Documents from Mirakl Marketplace

Information about the required documents can be retrieved by using an action based on GET HTTP request. The response will contain a list of documents provided for each Shop ID in JSON format.

Definition: GET /api/shops/documents?shop_ids=…

Where:
  • shop_ids – [required] A list of shop identifiers.

Request Model:

GET /api/shops/{shop_id}/documents
Authorization: Basic Pre-shared-APIKEY

Response Model:

{
"shop_documents": [
  {
  "date_deleted": null,
  "date_uploaded": "2019-08-01T03:38:32Z",
  "file_name": "bank statement.pdf",
  "id": 7973,
  "shop_id": 1234,
  "type": "ALL_PROOF_OF_BANK_ACCOUNT"
  },
  {
  "date_deleted": null,
  "date_uploaded": "2019-08-01T03:38:34Z",
  "file_name": "credit card bill.jpg",
  "id": 123,
  "shop_id": 1234,
  "type": "BILL"
  },
  {
  "date_deleted": null,
  "date_uploaded": "2019-08-01T03:38:51Z",
  "file_name": "article.pdf",
  "id": 124,
  "shop_id": 1234,
  "type": "LEGAL_ARTICLES_DISTR_OF_POWERS"
  },
  {
  "date_deleted": null,
  "date_uploaded": "2019-08-01T03:38:56Z",
  "file_name": "ID card.pdf",
  "id": 125,
  "shop_id": 1234,
  "type": "LEGAL_IDENTITY_OF_REPRESENTATIVE"
  },
  {
  "date_deleted": null,
  "date_uploaded": "2019-08-01T03:38:58Z",
  "file_name": "Business License.pdf",
  "id": 126,
  "shop_id": 1234,
  "type": "LEGAL_PROOF_OF_REGISTRATION_NUMBER"
  }
  ],
  "total_count": 5
  }

The following documents are required by Smart2Pay KYC platform:

  1. Bank statement (Not older than 6 months, with account holder and IBAN code visible);
  2. Company certificate / Incorporation certificate (Not older than 6 months);
  3. Register of directors (or any other document showing the company’s legal representatives) (Not older than 6 months);
  4. Passport copy of company’s legal representatives and UBO (Ultimate Beneficial Owners – all natural persons that own or control, directly or indirectly more than 25% of the Company): Legible ID copy in color within validity period;
  5. Take into consideration that for each of the company UBOs that own or control more than 25% of the company you must also provide proper identity documents (Legible ID copy in color within validity period)!

  6. Utility bill that can be used as proof of address for company’s legal representatives (Not older than 6 months).

Get the List of Shops from Mirakl Marketplace

Mirakl Marketplace Platform exposes an API which Smart2Pay can call to pull the list of newly created shops, using an action based on GET HTTP request. The response will contain a shop list in JSON format that returns all the shops that were created or updated after last_updated_date

Only a limited amount of details for each shop will be provided.

Definition: GET /api/shops?shop_ids=…&premium=…&state=…&updated_since=…&paginate=…

Where:
  • shop_ids – List of shop ids separated with comma. Limited to 100 values;
  • premium – Boolean : “ALL” (default), “FALSE” or “TRUE”. If TRUE (FALSE) returns only offers of premium (not premium) shop;
  • state – State of the shop;
  • updated_since – Filter all the shop that have been modified since the value of this parameter;
  • paginate – [optional] Control the pagination usage. Default : true.

Request Model:

GET /api/shops/{last_updated_date}
Authorization: Basic Pre-shared-APIKEY

Response Model:

 {
    "shops": [{
      "approval_delay": null,
      "approval_rate": null,
      "banner": null,
      "billing_info": {
        "bank_city": null,
        "bank_name": "Example",
        "bank_street": null,
        "bic": "ABCD1234",
        "iban": "IT123253453466453545",
        "owner": "Company example",
        "zip_code": null
      },
      "channels": [
        "INIT"
      ],
      "closed_from": null,
      "closed_to": null,
      "contact_informations": {
        "city": "X",
        "civility": "Mr",
        "country": "ITA",
        "email": "example@example.com",
        "fax": null,
        "firstname": "John",
        "lastname": "DOE",
        "phone": "(+39) 124567899",
        "phone_secondary": "(+39) 123456789",
        "state": null,
        "street1": "Street Test, 35",
        "street2": null,
        "web_site": null,
        "zip_code": "10123"
      },
      "currency_iso_code": "EUR",
      "date_created": "2019-12-08T14:25:43Z",
      "description": "\"\"\"Description goes here\"\"\"",
      "domains": [
        "PRODUCT"
      ],
      "evaluations_count": 0,
      "free_shipping": false,
      "grade": null,
      "immunity_date": null,
      "is_professional": true,
      "last_updated_date": "2019-12-02T15:24:08Z",
      "logo": null,
      "offers_count": 0,
      "operator_internal_id": null,
      "order_messages_response_delay": null,
      "orders_count": 0,
      "payment_details": {
        "paid_balance": 0.00,
        "pay_subscription": true,
        "payable_balance": 0.00,
        "payment_blocked": false,
        "pending_balance": 0.00,
        "subscription_free_from": null,
        "subscription_free_to": null
      },
      "payment_info": {
        "@type": "IBAN",
        "bank_name": "Example Bank",
        "bic": "ABCD123456",
        "iban": "IT132435456576867",
        "owner": "Example Company"
      },
      "premium": false,
      "premium_state": "DEFAULT",
      "pro_details": {
        "VAT_number": "LU123123",
        "corporate_name": "TEST",
        "identification_number": "123456789",
        "tax_identification_number": "LU123123"
      },
      "return_policy": null,
      "shipping_country": "ITA",
      "shipping_types": [
        "CSTANDARD"
      ],
      "shipping_zones": [
        "IT"
      ],
      "shippings": [
        {
          "additional_fields": [],
          "shipping_free_amount": null,
          "shipping_type_code": "CSTANDARD",
          "shipping_type_label": "Standard Courier  (2~4 days)",
          "shipping_zone_code": "IT",
          "shipping_zone_label": "Italy"
        }
      "shop_id": 1234,
      "shop_name": "Test Company",
      "shop_state": "SUSPENDED"
    },

Not all fields are mandatory in the above request! If Mirakl Marketplace does not provide all the necessary data, the shop representative will fill the missing fields in Smart2Pay platform. Another method of providing missing or incomplete data is by adding it in the additional fields and document fields in your Mirakl back office, if the initial configuration allows you to.

Once Smart2Pay identifies a newly created shop, it creates an account in Smart2Pay KYC platform for the shop representative and sends an email asking to finalize the application (e.g. fill missing info, upload documents, sign the online contract).

Company Documents

After you have completed all the necessary details for the company profile, you need to wait for Smart2pay approval of the company. After our team will review and approve your company details and documents, you will receive a confirmation message. Your company will be activated and you may start in completing the technical integration, that will get you closer to a full integration of your site with our platform.

Go to Company documents tab where you will see all the required documents that you need to provide us in order for us to generate your merchant agreement.

4

The documents that you necessarily need to provide us are the following: Bank statement, Company certificate / Incorporation certificate, Register of directors (or any other document showing individuals with signing rights), the passport copy of company’s legal representatives and utility bill that can be used as proof of address for company’s legal representatives. In case there are any other documents not covered by the above document requirements, you may upload them at point 6 in the form.

4

Once you uploaded the documents, you can click on the Submit Documents 26 button and wait for our team to review and approve the documents that you have sent.

4

If our team, while reviewing your documents, has agreed that you need to provide more information or the information is incomplete or outdated (like: expired passports or proof of address) they will reject your document. The reason will be stated in the form.

4

You will also receive a rejection message in your Inbox message stating the reason of rejection.

4

After resolving the issues involved in the rejection of the document, you will have to delete first the document from the Company Documents tab and then you will have to upload the newly modified document.

You will also receive a message in your Inbox message stating which document has been deleted and the person who has deleted the document.

4

After our team will review and approve the documents that you have sent, the Merchant agreement document is generated, in order to complete this step, all involved parties should accept it. The company representative that has the right to sign all company contracts will be notified via email in order to review and accept the merchant agreement.

4

You will also receive a message in your Inbox message stating that the company representative that has the right to sign company contracts has been notified via email.

4

Now that the company and all the documents have been approved and the merchant agreement has been accepted by all parties involved your company, your company will be approved. You will also receive your dashboard credentials and relevant API keys.

Once your company is activated, you may start in completing the technical integration, that will get you closer to a full integration of your site with our platform.

4

Messages

In the Messages tab from the main menu you can see all your messages received or sent by you and you can send messages to our team concerning the different problems that you encounter.

Through the Messages tab we offer our own messaging framework from within the program, to improve and facilitate the communication between us and our business partners. It is very useful because it displays all your notifications, keeps a track of your messages and you can always see the history of conversations between certain users and our team. Its a simple system to use and understand, it saves time with automated responses but it also manages all the conversations in the Inbox tab.

4

When you access the Inbox tab, the search Filters section is collapsed. In order to expand it, just click on the Show filters. You can search messages depending on the sender and receiver. Once you enter the desired filters just click on the Filter 26 button.

4

Capture scenarios for Paypal

Capture Scenarios Response Status Description Notification Status Description
The transaction has been fully captured.

Only payments with “Authorized” status (9) can be captured.
Final Status: 2 Success Final Notification Status: 2 Success
The payment has been partially captured.

Only payments with “Authorized” status can be partially captured. The payment has been sent out to be partially captured, but the payment gateway has not yet confirmed that the payment is successful.
Final Status: 35 Partially Captured Final Notification Status: 35 Partially Captured
Capture Failed Scenarios Return Code Description
The transaction could not be captured.

The transaction is not in an Authorized status (it has already been fully Captured or Partially Captured).
Return Code: 17 Payment is invalid

For a complete list of all the possible Return Code IDs go to our section GlobalPay Return Codes.

See the request – response examples for the above possible scenarios:

  • Success Status

    A payment can only be captured if it has an Authorized status. Once the payment has an Authorized status (9), you can capture either the full amount or a partial amount of the initial authorized amount for the transaction.

    A 200 HTTP response (OK) is returned if the request was completed successfully.

    Full capture means you capture the entire authorized amount for the initial transaction.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4813936/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4813936,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20191121152453",
            "MerchantTransactionID": "s2ptest_p1",
            "OriginatorTransactionID": null,
            "Amount": 100,
            "Currency": "EUR",
            "CapturedAmount": "100",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 94,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": "20191121152731",
            "Customer": null,
            "BillingAddress": {
                "ID": 452,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "ES"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": null
            },
            "Fraud": null,
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=917D36F62AAA2BE344A324E612A0B5CC.4813936"
        }
    }

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
        "Payment": {
            "ID": 4813936,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20191121152453",
            "MerchantTransactionID": "s2ptest_p1",
            "OriginatorTransactionID": null,
            "Amount": 100,
            "Currency": "EUR",
            "CapturedAmount": "100",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 94,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": "20191121152731",
            "Customer": null,
            "BillingAddress": {
                "ID": 452,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "ES"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": null
            },
            "Fraud": null,
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=917D36F62AAA2BE344A324E612A0B5CC.4813936"
        }
    }

  • Partially Captured Status

    Partial capture means you have the possibility to capture a smaller amount than the one from the initial authorized transaction. Partial capture is used when you have sent at least part of the order to the consumer and want to capture the amount for the item(s) that have been shipped.

    You can perform only one partial capture for an authorized transaction with the limitation that the amount of the partial capture to be smaller or equal than the initial authorized amount.

    Specify only the captured amount parameter in the query string, in order to partially capture the payment, like in the below example:

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4813937/capture?amount=50
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4813937,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20191121153210",
            "MerchantTransactionID": "s2ptest_p2",
            "OriginatorTransactionID": null,
            "Amount": 100,
            "Currency": "EUR",
            "CapturedAmount": "50",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 94,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": "20191121153324",
            "Customer": null,
            "BillingAddress": {
                "ID": 452,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "ES"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 35,
                "Info": "PartiallyCaptured",
                "Reasons": null
            },
            "Fraud": null,
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=387EE786392FE554A86CA9E3F3EF1E09.4813937"
        }
    }

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk={
        "Payment": {
            "ID": 4813937,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20191121153210",
            "MerchantTransactionID": "s2ptest_p2",
            "OriginatorTransactionID": null,
            "Amount": 100,
            "Currency": "EUR",
            "CapturedAmount": "50",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 94,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": "20191121153324",
            "Customer": null,
            "BillingAddress": {
                "ID": 452,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "ES"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 35,
                "Info": "PartiallyCaptured",
                "Reasons": null
            },
            "Fraud": null,
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=387EE786392FE554A86CA9E3F3EF1E09.4813937"
        }
    }

  • Return Code: 17 – Payment is invalid

    The transaction could not be captured. The transaction is not in an Authorized status. You can receive this response when the payment you want to Capture is not Authorized or when the payment has already been Captured.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4813935/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8{
        "Payment": {
            "ID": 4813935,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20191121151256",
            "MerchantTransactionID": "s2ptest_paypal2",
            "OriginatorTransactionID": null,
            "Amount": "100",
            "Currency": "EUR",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 94,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30201,
            "NotificationDateTime": "20191121151441",
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": [
                    {
                        "Code": "17",
                        "Info": "Payment is invalid - 4813935"
                    }
                ]
            },
            "Fraud": null,
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }

PayPal Test Data

For PayPal payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PayPal Payment Flow

  1. The Customer selects his preferred currency from the list and enters his email address.1 Enter email
  2. The customer logs in to his PayPal account by entering his email address and password.1 Account login
  3. The Customer reviews the payment information and confirms the payment.1 Payment details
  4. Upon completion of the payment flow the customer is redirected back to your ReturnURL.1 Return page when the redirection status is a success

Company details

The first part that needs to be covered for a successful onboarding at Smart2Pay is signing up your company! This section provides insights on how to successfully complete the Company Details form. Please keeep in mind, that all the fields are mandatory and we encourage you to give us the necessary information with utmost consideration!

Access the OnBoarding platform by clicking on the Go button from the Company Details form in the Welcome Page.

4

On the OnBoarding platform you will need to provide us with documentation requirements for customer and company, upload necessary company documents, accept the merchant agreement and request the company activation in order for your company to be approved and be ready to takle the live transactions.

We’ll take step by step in filling all the necessary forms and you have the possibility to always check your boarding status in the Overview tab. Start by filling in the Company details form and provide as many details. Don’t forget to save the changes.

4

In the Company tab you will need to provide us with documentation requirements for customer and company, like: Company details and address, Company contacts, Company bank details and also Stakeholders information.

In the case that your business isn’t registered for VAT, in the EEC VAT Number filed you will click on the Not Applicable sign.

In order for us to understand and to know more about your business and services, please provide as much information about your products or services in the Business Model field.

If you have more than one website where you want to implement our services, you need to add each one of them by using the ADD ANOTHER SITE 26 button.

4

In order to complete the Contact Details form, you will have to choose from one of the roles provided in the form: Financial Contact, Technical Contact or Support Contact, according to your role within the company. Click on the appropriate button and add the desired contact type.

4

After choosing the specific role within the company, please provide the necessary details by which a person can contact you: first and last name and email address. For a more accurate and efective communication, you can give us more than one company contact.

4

You will also need to provide the current headquarters address for your company, like: Street number, Postcode / Zipcode, City /State, Phone / Fax, and Country of establishment.

4

In the Company Bank Details you will have to provide information related to your Bank, like: Bank Name, Account Holder, Account Currency, IBAN, Account Number and SWIFT. In case you dont’t have the complete information, please contact your Bank for a complete answer.

4

The Stakeholders form must contain details of each Company Representative with signing rights or/and Ultimate Beneficial Owner that owns or controls, directly or indirectly more than 25% of the Company.

4

Add a Company representative and fill in the necessary information, like: their signing right (click only if the person has the right to sign all company contracts), Legal Name, Email, Date of Birth, and their complete address. In order to add a new company representative just use the ADD button.

4

Add an Ultimate Beneficial Owner / Share Holder and fill in the necessary information, like: Legal Name, Email, Percentage of ownership of the company, Date of Birth, and their address. In order to add a new Beneficial Owner / Share Holder just use the ADD button.

4

After you have completed all the necessary fields, just click on the Save Changes button and request the company activation. You may place a request to activate the company every 24 hours.

The Request Activation button will only appear if the Company representative form is completed with the necessary information!

4

You will now have access to the Company documents where you will have to provide us the relevant official documents.

Reset Password

In case you forgot your password or you want to reset it, click on the Forgot your password link form the Sign In form.

5

Enter your email address and click on the Send Verification Code.

5

Enter the verification code sent to your email address in the correct field in order to verify it.

5

After the email address is successfully verified click on the Continue button.

5

As an additional measure of security you will be prompted to send a verification code to your phone number.

5

Enter the verification code sent to your phone number via SMS in the correct field.

5

You need to enter a new password and to confirm it. Click on the Continue button in order to complete the sign in process.

5

You are redirected to the Sign In page, where you enter your email address and the newly updated password.

5

Single Sign-On Connection

Upon the creation of your Onboarding account we have also created for you a Documentation account, a Dashboard TEST account and also a Dashboard LIVE account with the same user name and password.

This means that you can access all of the Smart2pay platforms with the same email address and password that you provided when created the Onboarding account. Sign-in to the Smart2Pay system will be very easy and quick. One set of credentials to four different platforms:

Each platform decides if a user has access rights to login in the application and what roles are defined. This way, if a user has an account in Onboarding Platform and is approved for live account, he will be able to use the same password for all accounts.

Registration Process

With an easy to manage and secure registration process, it will only take a little time for you to manage the onboarding process!

After clicking the Sign up button from the top of the page you will be redirected to a Getting Started with Smart2Pay page where you will find the necessary steps you will need to make for a successful onboarding process!

Signing up your company is the first part that needs to be covered for a successful onboarding at Smart2Pay.

5

You will need to cover the following:

  • Company Details: access the provided URL and provide us with the basic information about your company and the relevant official documents;
  • Accept Merchant Agreement: you need to the accept merchant agreement we will send you;
  • Request company activation: you will receive a digital request to activate your company on our systems;
  • Company Approved: If all company details and documents are validated we will approve your company and give you your dashboard credentials and relevant API keys.

The second part that needs to be coverd is completing the technical integration, that will get you closer to a full integration of your site with our platform.

5

You will need to cover the following:

  • Integrate the Smart2Pay REST API: follow our Online Documentation;
  • Set up and code the Notification URL: follow the steps here: Payment Notification;
  • Get familiar with our TEST Merchant Dashboard;
  • Company Approved: your company is approved and you have completed the technical integration process. Fine tune your integration and GO LIVE!

In order for you to register a new account for the Onboarding system click on the Sign Up button from the top of page or browse the following URL: https://www.smart2pay.com/microsoft/signup/.

The registration process involves providing us your email address to which we will send you a verification code. After entering your email address click on the Send Verification Code button.

4

You will receive an email with the verification code that you will further use in the registration process.

4

The user enters the verification code received via email in the Sign Up form and clicks on the Verify Code button.

Please keep in mind that the verification code received via email expires after 5 minutes! After that time you will need to send another verification code to your email address by clicking on the Send New Code button.

4

In the next step, you will be required provide a few account details, like: password, country/region, domain, first name, last name and job title. After entering the required information click on the Create account button.

  • Password: enter a new password for your newly created account and then confirm it;
  • Country/Region: select your country from the provided drop-down list;
  • Domain: enter your website domain (wwww.example.com);
  • First Name: enter your first name;
  • Last Name: enter your last name;
  • Job Title: specify your job title.

5

By clicking on the Create button a new user has been created for all of the Smart2pay platforms. You can access all of the Smart2pay platforms with the same email address and password that you have chosen. For more information regarding Smart2Pay platforms go to Single Sign-On connection.

Once you finnished creating your account, you will be redirected to a Getting Started with Smart2Pay page where you will be registered with your newly created user. All you need to do now is follow the steps we outlined for a successful onboarding process!

5

Company Onboarding

Onboarding is the tool that you need in order that the onboarding process to be quick and accurate and to ensure a long-term and successful business partnership. We have developed an intuitive and secure online system that it will allow merchants for an automated and quick onboarding process.

It will only take a little time for you to manage the onboarding process. We have strive to minimize the long and tiresome process during merchant boarding and the ongoing challenges of completing forms and fields while building the merchant’s and company’s profile.

Get a list of Captures of a specific card payment

You can get a list of all partial captures for a specific direct card payment by using an action based on GET HTTP request. Please be aware that only a limited amount of details for each capture will be provided.

Definition: GET /v1/payments/{id}/captures

Where:
  • {id} – GlobalPay Payment ID

Request:

GET https://securetest.smart2pay.com/v1/payments/202247/captures
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Captures": [
  {
    "ID": 266,
    "SiteID": 1010,
    "Created": "20161205095522",
    "MerchantTransactionID": "s2ptest_h22",
    "OriginatorTransactionID": null,
    "PaymentID": 202247,
    "Amount": 500,
    "Currency": "EUR",
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
      }
    },
    {
    "ID": 267,
    "SiteID": 1010,
    "Created": "20161205095522",
    "MerchantTransactionID": "s2ptest_h23",
    "OriginatorTransactionID": null,
    "PaymentID": 202247,
    "Amount": 2000,
    "Currency": "EUR",
    "Status": {
      "ID": 4,
      "Info": "Failed",
      "Reasons": [
        {
          "Code": "2209",
          "Info": "Capture.Amount exceeds authorization amount"
          }
        ]
      }
    }
  ]
}

You can also get information for a specific capture of a direct card payment by using an action based on GET HTTP request.

Definition: GET /v1/payments/{id}/capture/{id}

Where:
  • payments/{id} – GlobalPay Payment ID
  • capture/{id} – The ID of the specific capture

Request:

GET https://securetest.smart2pay.com/v1/payments/202247/captures/266
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Capture": {
        "ID": 266,
        "SiteID": 1010,
        "Created": "20161205095522",
        "MerchantTransactionID": "s2ptest_h22",
        "OriginatorTransactionID": null,
        "PaymentID": 202247,
        "Amount": 500,
        "Currency": "EUR",
        "Status": {
            "ID": 2,
            "Info": "Success",
            "Reasons": []
        }
    }
}

Smart2Pay Mirakl Plugin for Marketplaces

Looking for one marketplace-focused solution, which is also fully compliant with the PSD2 regulatory requirements?

You’re in the right place!

Our solution for marketplace platforms has been designed to seamlessly integrate with Mirakl’s e-marketplace products and allows for fully customizable marketplace onboarding and split payments processes.

Mirakl Marketplace Platform is one of the most modern, flexible, and feature-rich Marketplace solution available, with years of best practices built in and also offering clients unparalleled expertise from their team of 30+ business, technical, and operational marketplace experts.

Not using Mirakl? No problem: we also offer Marketplace APIs to help you manage marketplace payments. More info here: https://docs.smart2pay.com/category/marketplace-api/.

The solution provides access to credit card payments and alternative payment methods for a Marketplace in a simple yet reliable legal and technical setup.

We are committed to help marketplaces run their business without worrying about the associated regulatory requirements from the new PSD2 directive which have come into force beginning 2018.

Smart2Pay solution ensures that all of the participating shops as well as the marketplace will benefit of a seamlessly onboarding process, reliable and secure transaction processing, reconciliation to the penny and prompt settlements.

The Mirakl plugin features:

  • automated import of all the the newly created shops and required documents from Mirakl to Smart2pay platform – leading to a fully customizable and seamless onboarding process.
  • automated shop approval notification which contains all info you need to start processing right away. More info here: https://docs.smart2pay.com/category/marketplace-api/shop-approval-notification/.
  • automated import of all payment instructions to marketplace participants and handling all the commission fees for the marketplace operator. Please discuss with our technical support the setup of your Mirakl voucher generation process.
  • supporting a wide range of payment methods from credit card payment to alternative payment methods with an all-in-one unified API and settlement flow. 

Here is how it works:

1 Marketplace - Processes and Systems

The technical process (KYC Flow) with all the necessary steps is described next:

    All KYC processes related to marketplace onboarding of the participating shops take place in Mirakl KYC system. All KYC processes related to payments take place in Smart2Pay KYC system.

  • Mirakl Marketplace accepts a new shop on its platform and creates an entry in its database.
  • Mirakl Marketplace exposes an API which Smart2Pay KYC platform calls several times per day to pull information about the newly created shops.
  • Smart2Pay KYC platform pulls all available information about the shop (ShopID, Alias, shop representative e-mail, documents etc.). If all the required information is not available, the merchant representative will have to fill it in on Smart2Pay KYC platform.
  • Smart2Pay will create an account for the shop in the Smart2Pay KYC platform and send an e-mail to the shop representative with the login details.
  • The shop representative will fill in any missing company related data and upload KYC/UBO specific documentation.
  • The shop representative signs online the Merchant agreement for Payment processing.
  • Smart2Pay Risk team reviews the company.
  • In case of approval, a siteID is generated in the Smart2Pay platform.
  • Smart2Pay will do a push notification to a page designated by Mirakl with the following info ShopID, SiteID, APIKEY. The last two parameters need to be used when calling Smart2Pay REST API when processing the payments. Mirakl Marketplace needs to respond with HTTP return code 204 (No content) to the POST notification.

Please contact our support team at support@smart2pay.com to schedule a more in depth demo on how we help your marketplace to process payments and perform split settlements.

Exemptions to Strong Customer Authentication (SCA)

With the Second Payment Services Directive (PSD2), the new set of laws and regulations for payment services in the European Union (EU) and the European Economic Area (EEA), Strong Customer Authentication (SCA) will be the requirement for all online transactions. However, there are still some exemptions from this rule where specific types of low-risk payments may be still exempted from Strong Customer Authentication (SCA).

Please keep in mind that banks can choose not to honor these exemptions and you need to be prepared to handle a SCA challenge even if the transactions has been submitted under one of the below exemptions.

The most relevant SCA exemptions are:

  • MIT
  • Low Risk / TRA
  • Low Value
  • Secure Corporate payments
  • Trusted Beneficiaries

1. Merchant Initiated Transaction (MIT)

MITs are payment transactions that are not initiated by the payer but by the payee only and are not subject to strong customer authentication (SCA) to the extent that these transactions are initiated without any interaction or involvement of the payer. MIT transactions are subjected to SCA except when a mandate is signed by the client. For example, SEPA Direct Debits are initiated by the merchant but have a direct debit mandate signed by the end customer. Thus, SCA is not applicable in this case and there are no restrictions to the frequency or the amount (obtained scheme transaction identifier needs to be provided for use in the subsequent transactions).

Adjustment of initial Authorisation allows merchants to increase or decrease the authorised amount after the initial authorisation has taken place is also MIT. This enables tipping.

2. TRA – Transactional Risk Analysis

SCA can be deactivated for online payments between €30 and €500, depending on the payment providers fraud rates (see table below). There are no low-risk exemptions for transactions over €500. Merchants have to rely on a payment service provider (e.g. an acquirer) to act upon their request. In addition, the test to trigger the exemption rests with whether the PSP satisfies the prescribed conditions, not the merchants themselves. Smart2Pay keeps a very low fraud rate by using state of the art anti-fraud solutions such as RedShield, Machine Learning algorithms and by working with low risk acquiring banks which have very good fraud scores.

Adding additional information in the payment request will maximize the probability of getting the exemption by Issuers. The chargeback liability shifts to the issuer as well.

Regulatory Technical Standards (RTS), that payment providers need to take into account through real-time risk analysis, covers the following:

  • abnormal spending or behavioral pattern of the payer;
  • unusual information about the payer’s device/software access;
  • malware infection in any session of the authentication procedure;
  • known fraud scenario in the provision of payment services;
  • abnormal location of the payer;
  • high-risk location of the payee.

The fraud rate limits for payment providers are being applied as follows:

Fraud rate and amount limits
Fraud transaction rate Amount limits
Up to 0.01% Up to €500
Up to 0.06% Up to €250
Up to 0.13% Up to €100

3. Low value: Small amounts less than 30 EUR

For a transaction of less than 30 EUR and up to 100 EUR accumulated or up to 5 transactions since the last SCA. Beyond 100 EUR or beyond 5 unauthenticated transactions, a new SCA is required. Keep in mind that since the information needed to validate these stipulations is only available to the issuing bank, you will still need to confirm if SCA is required on all transactions that might fall into this exemption category.

4. Payment to a trusted beneficiary

Customers can add their preferred online sellers to a list of trusted beneficiaries held by the issuing bank, so that they don’t required to authenticate for each new payment. Please instruct your customers if possible to add your business to the white-list at their bank.

5. Secure Corporate payments

SCA can de deactivated for corporate card payments made through secure processes and protocols initiated by businesses and not available for consumers. Payments that are included in this category are those made through central travel accounts, lodged cards, virtual cards, and secure corporate cards, like the ones used in a corporate travel management system.

See below an example of a MerchantInitiatedTransaction (MIT) transaction type:

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_m10",
    "Amount": 1000,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",   
    "Card": {
      "HolderName": "John Doe",
      "Number": "4548812049400004",
      "ExpirationMonth": "05",
      "ExpirationYear": "2021",
      "SecurityCode": "123"     
      },
     "3DSecure": true,
     "DeviceInfo": {
      "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
      "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
      "BrowserJavaEnabled": false,
      "BrowserJavaScriptEnabled": true,
      "BrowserLanguage": "ro-RO",
      "BrowserColorDepth": "24",
      "BrowserScreenHeight": "1080",
      "BrowserScreenWidth": "1920",
      "BrowserTimeZone": "-180"
    },         
    "ScaExemption": "MerchantInitiatedTransaction"
  }
}

There are 2 possible response scenarios:

  • Exemption is approved: The cardholder’s bank receives the request, assesses the risk level of the transaction, and approves the exemption and the SCA is no more necessary. The payment has status Authorized / Captured in the response.

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 172498,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190913075654",
        "MerchantTransactionID": "s2ptest_m10",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
       "Description": "silviu test",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "Test Person",
          "Number": "VISA-0004",
          "ExpirationMonth": "05",
          "ExpirationYear": "2021"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "971896",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "3DSecureData": null,   
        "ScaExemption": "MerchantInitiatedTransaction",
        "CardOnFile": null,
        "Fraud": null
      }
    }
    

  • Exemption is rejected: The cardholder’s bank receives the request, assesses the risk level of the transaction, and rejectes the exemption and the SCA is mandatory. The payment has status Open in the response. The customer accesses the RedirectURL form the response and is redirected to the 3D Secure page to authenticate the transaction.

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 172498,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190913075654",
        "MerchantTransactionID": "s2ptest_m10",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "silviu test",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "Test Person",
          "Number": "VISA-6852",
          "ExpirationMonth": "05",
          "ExpirationYear": "2020"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": null,
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": "http://85.186.26.139:58938/v1/Payments/FillCardDetails?PaymentToken=172500.1006.5CD50C1B1707FB83EAA7655F9B21D42E9&SkipLandingPage=true",
        "3DSecure": true,
        "3DSecureData": null,   
        "ScaExemption": "MerchantInitiatedTransaction",
        "CardOnFile": null,
        "Fraud": null
      }
    }

Card on file transactions (COF)

A card-on-file transaction is a transaction where a cardholder authorizes a merchant to store the cardholder’s payment details, and also authorizes that same merchant to bill the cardholder’s stored account.

Transactions are either initiated by a consumer, or by a merchant based on the instructions given to them by the consumer. It is possible for a merchant to initiate a transaction without consumer action.

Consumer-Initiated Transactions (CIT): where the consumer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. A consumer-initiated transaction contains proof (such as track data, chip data with cryptograms, cardholder verification methods, and online through the presence of Card Verification Value 2 (CVV2) or Verified by Visa (VBV) authentication data) that the cardholder was involved in the transaction.

Merchant-Initiated Transactions (MIT): a transaction that depends to a previous consumer-initiated transaction, but it is conducted without the consumer being present and without any additional cardholder validation performed. It’s a transaction based on a previous agreement between the consumer and the merchant for a recurring product or service or an automated billing or unscheduled transactions etc.

Don’t miss out the below examples with CardOnFile object used for the initial transaction and also for a subsequent one.

Card On File (COF) Transaction Types
Type Description
Installments Deferred payment. Always referring to an INDIVIDUAL purchase, the amount of the several transactions is fixed, and with a definite time interval.
Recurring Recurring payment. The amount of transactions can be fixed or variable, and with a defined time interval.
Reauthorization Normally before partial shipments. Also, when the client extends the stay in hotel / rental of the vehicle or when, having an estimated authorization, the final amount is requested (“settlement”).
Resubmission Original denied because of “balance”; only for certain sectors of activity (for more details check the regulations of the brands) and with a maximum number of days from the purchase. Relevant example:”Transport”.
Delayed Those that happen after the transaction for services rendered / used unknown at the beginning. (Minibar, vehicle damage, fines ….)
Incremental When additional services are incurred during the contract period.
No Show When the merchant charges services to which the owner committed, but then failed to comply with the agreed terms. Relevant example: unattended reservations at hotels without cancellation.
Other The rest of COF transactions that do not fit with any of the previous ones.
  • For an initial transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to true.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
      "MerchantTransactionID": "s2ptest_11a",
      "Amount": "100",
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "Test Description",
      "StatementDescriptor1": "Dynamic Test Description",
      "Card": {
        "HolderName": "Test Person",
        "Number": "4012005162084369",
        "ExpirationMonth": "05",
        "ExpirationYear": "2020",
        "SecurityCode": "123",
        "RequireSecurityCode": true
        },
      "Capture": false,
      "Retry": false,
      "GenerateCreditCardToken": false,
      "PaymentTokenLifetime": 10,
      "3DSecure": true,
      "DeviceInfo": {
        "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
        "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
        "BrowserJavaEnabled": false,
        "BrowserJavaScriptEnabled": true,
        "BrowserLanguage": "ro-RO",
        "BrowserColorDepth": "24",
        "BrowserScreenHeight": "1080",
        "BrowserScreenWidth": "1920",
        "BrowserTimeZone": "-180"
        },
      "CardOnFile":{
             "IsInitial": true,
             "TransactionType": "Recurring"
          },
      "Language": "ro-RO",
      "SkinID": 200
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 1234,
            "ClientIP": null,
            "SkinID": 200,
            "Created": "20190828091954",
            "MerchantTransactionID": "s2ptest_11a",
            "OriginatorTransactionID": null,
            "Amount": "100",
            "Currency": "EUR",
            "CapturedAmount": "0",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": "Test Description",
            "StatementDescriptor": "Static Description",
            "MethodID": 6,
            "MethodOptionID": null,
            "SiteID": 1010,
            "NotificationDateTime": null,
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Card": {
                "HolderName": "Test Person",
                "Number": "VISA-4369",
                "ExpirationMonth": "05",
                "ExpirationYear": "2020"
            },
            "CreditCardToken": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": []
            },
            "MethodTransactionID": null,
            "AuthorizationCode": "591659",
            "PaymentTokenLifetime": 10,
            "Capture": false,
            "Retry": false,
            "RedirectURL": null,
            "3DSecure": true,
            "DeviceInfo": {
                "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
                "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
                "BrowserJavaEnabled": false,
                "BrowserJavaScriptEnabled": true,
                "BrowserLanguage": "ro-RO",
                "BrowserColorDepth": "24",
                "BrowserScreenHeight": "1080",
                "BrowserScreenWidth": "19200",
                "BrowserTimeZone": "-180"
            },
            "ScaExemption": null,
            "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring"
            },
            "Fraud": {
                "Status": "Accept",
                "Score": 31,
                "Reason": "No decision provided"
            }
        }
    }

  • Transaction that depends to the previous consumer-initiated transaction. For a transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to false.For subsequent payments always send in the request the InitialPaymentID parameter in the CardOnFile object.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
      "MerchantTransactionID": "s2ptest_12a",
      "Amount": "100",
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "Test Description",
      "StatementDescriptor1": "Dynamic Test Description",
      "Card": {
        "HolderName": "Test Person",
        "Number": "4012005162084369",
        "ExpirationMonth": "05",
        "ExpirationYear": "2020",
        "SecurityCode": "123",
        "RequireSecurityCode": true
        },
      "Capture": false,
      "Retry": false,
      "GenerateCreditCardToken": false,
      "PaymentTokenLifetime": 10,
      "3DSecure": true,
      "DeviceInfo": {
        "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
        "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
        "BrowserJavaEnabled": false,
        "BrowserJavaScriptEnabled": true,
        "BrowserLanguage": "ro-RO",
        "BrowserColorDepth": "24",
        "BrowserScreenHeight": "1080",
        "BrowserScreenWidth": "1920",
        "BrowserTimeZone": "-180"
        },
      "ScaExemption": "MerchantInitiatedTransaction",
      "CardOnFile":{
        "IsInitial": false,
        "TransactionType": "Recurring",
        "InitialPaymentID": 1234        
        },
      "Language": "ro-RO",
      "SkinID": 200
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 12345,
            "ClientIP": null,
            "SkinID": 200,
            "Created": "20190828091954",
            "MerchantTransactionID": "s2ptest_12a",
            "OriginatorTransactionID": null,
            "Amount": "100",
            "Currency": "EUR",
            "CapturedAmount": "0",
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": "Test Description",
            "StatementDescriptor": "Static Description",
            "MethodID": 6,
            "MethodOptionID": null,
            "SiteID": 1010,
            "NotificationDateTime": null,
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Card": {
                "HolderName": "Test Person",
                "Number": "VISA-4369",
                "ExpirationMonth": "05",
                "ExpirationYear": "2020"
            },
            "CreditCardToken": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": []
            },
            "MethodTransactionID": null,
            "AuthorizationCode": "591659",
            "PaymentTokenLifetime": 10,
            "Capture": false,
            "Retry": false,
            "RedirectURL": null,
            "3DSecure": true,
            "DeviceInfo": {
                "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
                "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
                "BrowserJavaEnabled": false,
                "BrowserJavaScriptEnabled": true,
                "BrowserLanguage": "ro-RO",
                "BrowserColorDepth": "24",
                "BrowserScreenHeight": "1080",
                "BrowserScreenWidth": "19200",
                "BrowserTimeZone": "-180"
            },
            "ScaExemption": "MerchantInitiatedTransaction",
            "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 1234
              },
            "Fraud": {
                "Status": "Accept",
                "Score": 31,
                "Reason": "No decision provided"
            }
        }
    }

3D Secure 2.0 Pass-Through Payments

You can submit a request to authorize payments using authentication data from your own 3D Secure MPI provider, by sending the necessary 3D Secure parameters listed below in the object 3DSecureData.

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_3a",
    "Amount": "100",
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "Test Description",
    "StatementDescriptor": "Dynamic Test Description",
    "Card": {
      "HolderName": "Test Person",
      "Number": "4012005162084369",
      "ExpirationMonth": "05",
      "ExpirationYear": "2020",
      "SecurityCode": "123",
      "RequireSecurityCode": true
    },
    "Capture": false,
    "Retry": false,
    "GenerateCreditCardToken": false,
    "PaymentTokenLifetime": 10,
    "3DSecure": true,
    "3DSecureData": { 
      "AuthenticationStatus": "Y",
      "ECI": "05",
      "CAVV": "MDA5ODYyNjQxMzEyNzQxMTQ4NzA=",
      "DSID": "f41f41f-f412f-41f-4321-f4132f4",
      "3DSecureVersion": "2.1.0"
      },
    "ScaExemption": "LowValueTransaction",
    "Language": "ro-RO",
    "SkinID": 200
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 208158,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190828082527",
        "MerchantTransactionID": "s2ptest_3a",
        "OriginatorTransactionID": null,
        "Amount": 100,
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Test Description",
        "StatementDescriptor": "Dynamic Test Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
            "HolderName": "Test Person",
            "Number": "VISA-4369",
            "ExpirationMonth": "05",
            "ExpirationYear": "2020"
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "143383",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "3DSecureData": {
            "AuthenticationStatus": "Y",
            "ECI": "05",
            "CAVV": "MDA5ODYyNjQxMzEyNzQxMTQ4NzA=",
            "DSID": "f41f41f-f412f-41f-4321-f4132f4",
            "3DSecureVersion": "2.1.0"
        },
        "DeviceInfo": null,
        "ScaExemption": "LowValueTransaction",
        "Fraud": {
            "Status": "Accept",
            "Score": 31,
            "Reason": "No decision provided"
        }
    }
}

3D Secure 2.0 Payments

3D Secure 2.0 is the new authentication protocol that provides an additional layer of verification for card transactions. Strong Customer Authentication (SCA) requires merchants to integrate into the checkout flow a two-factor authentication, requiring their customers to use two out of three elements: something only the user knows like a password, something only the user possesses like the phone and something only the user possesses like a fingerprint.

Checkout the below example of a payment using the 3D Secure 2.0 protocol.

Although 3D Secure 2.0 protocol requires sending much more additional details, it increases the chances for a smooth and frictionless payment flow.

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
  "MerchantTransactionID": "s2ptest_6a",
  "Amount": "100",
  "Currency": "EUR",
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "Test Description",
  "StatementDescriptor1": "Dynamic Test Description",
  "BillingAddress": {
    "City": "Iasi",
    "ZipCode": "7000-49",
    "State": "Iasi",
    "Street": "Sf Lazar",
    "StreetNumber": "37",
    "HouseNumber": "5A",
    "HouseExtension": "-",
    "Country": "RO"
    },
  "ShippingAddress": {
    "City": "Iasi",
    "ZipCode": "700049",
    "State": "Iasi",
    "Street": "Sf Lazar",
    "StreetNumber": "37",
    "HouseNumber": "-",
    "HouseExtension": "-",
    "Country": "RO" 
    },
  "Customer": {
    "MerchantCustomerID": "3452342354232",
    "Email": "accept@accept.com",
    "Firstname": "Test",
    "Lastname": "Person",   
    "SocialSecurityNumber": "45908-28324",
    "Phone": "0744-783322",
    "Company": "S2P",
    "Gender": "1"
    },
  "Card": {
    "HolderName": "Test Person",
    "Number": "4012005162084369",
    "ExpirationMonth": "05",
    "ExpirationYear": "2020",
    "SecurityCode": "123",
    "RequireSecurityCode": true
    },
  "Capture": false,
  "Retry": false,
  "GenerateCreditCardToken": false,
  "PaymentTokenLifetime": 10,
  "3DSecure": true,
  "DeviceInfo": {
    "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
    "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
    "BrowserJavaEnabled": false,
    "BrowserJavaScriptEnabled": true,
    "BrowserLanguage": "ro-RO",
    "BrowserColorDepth": "24",
    "BrowserScreenHeight": "1080",
    "BrowserScreenWidth": "1920",
    "BrowserTimeZone": "-180"
    },
  "ScaExemption": "LowValueTransaction",
  "Language": "ro-RO",
  "SkinID": 200
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 208161,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190828091954",
        "MerchantTransactionID": "s2ptest_6a",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Test Description",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": {
            "ID": 647,
            "MerchantCustomerID": "3452342354232",
            "Email": "accept@accept.com",
            "FirstName": "Test",
            "LastName": "Person",
            "Gender": "1",
            "SocialSecurityNumber": "45908-28324",
            "Phone": "0744-783322",
            "Company": "S2P"
        },
        "BillingAddress": {
            "ID": 253,
            "City": "Iasi",
            "ZipCode": "7000-49",
            "State": "Iasi",
            "Street": "Sf Lazar",
            "StreetNumber": "37",
            "HouseNumber": "5A",
            "HouseExtension": "-",
            "Country": "RO"
        },
        "ShippingAddress": {
            "ID": 87,
            "City": "Iasi",
            "ZipCode": "700049",
            "State": "Iasi",
            "Street": "Sf Lazar",
            "StreetNumber": "37",
            "HouseNumber": "-",
            "HouseExtension": "-",
            "Country": "RO"
        },
        "Articles": null,
        "Card": {
            "HolderName": "Test Person",
            "Number": "VISA-4369",
            "ExpirationMonth": "05",
            "ExpirationYear": "2020"
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "591659",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "DeviceInfo": {
            "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
            "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
            "BrowserJavaEnabled": false,
            "BrowserJavaScriptEnabled": true,
            "BrowserLanguage": "ro-RO",
            "BrowserColorDepth": "24",
            "BrowserScreenHeight": "1080",
            "BrowserScreenWidth": "19200",
            "BrowserTimeZone": "-180"
        },
        "ScaExemption": null,
        "Fraud": {
            "Status": "Accept",
            "Score": 31,
            "Reason": "No decision provided"
        }
    }
}

PayWithMyBank Recurring Payment

Definition: POST /v1/payments/recurrent

A recurring payment is created in the same manner a one-off payment is created. In addition, you need to send the PreapprovalID (the PreapprovalID received when you created/opened a preapproval) and the information specific to each payment method.

For PayWithMyBank (58), you need to send the PreapprovalID (the PreapprovalID received when you created/opened a preapproval) and the Amount to be captured:

Request:

POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk={
 "Payment": {
   "PreapprovalID": 19800,
   "MerchantTransactionID": "s2ptest_h-1",
   "Amount": 20,
   "Currency": "USD",
   "MethodID": 58
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4722746,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190729142257",
        "MerchantTransactionID": "s2ptest_h-1",
        "OriginatorTransactionID": null,
        "Amount": "20",
        "Currency": "USD",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "",
        "MethodID": 58,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 19800,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "Fraud": null,
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

Please be aware that the final status of the payment can be received in up to 3 business days depending on the customer’s Bank used!

PayWithMyBank Close a Preapproval

Definition: DELETE /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

To close a preapproval, you must send a DELETE action for an existing preapproval object.

Checkout the below example to close a preapproval for PayWithMyBank (58):

Request:

DELETE https://paytest.smart2pay.com/v1/preapprovals/19800
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Update: 1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 4,
            "Info": "ClosedByCustomer",
            "Reasons": null
        },
        "RedirectURL": null,
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

PayWithMyBank Change a Preapproval

Definition: PATCH /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

You can change the attributes of an already created preapproval by applying a PATCH.

Checkout the below example to change a preapproval for PayWithMyBank (58):

Request:

PATCH https://paytest.smart2pay.com/v1/preapprovals/19800
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_h-1",
   "PreapprovedMaximumAmount": 20,
   "Currency": "USD",
   "Description": "Update: 1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 58,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "US"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Update: 1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/PWMB/Landing/PreapprovalLanding.aspx?ID=15352&Hash=8FCF71570B0E7CE025C33B27E34F4493",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

PayWithMyBank Preapproval Notification

Upon successful approval, we will notify you about the new status of the preapproval to the URL you setup in the Merchant Dashboard.

You need to respond with HTTP Status 204 (No Content)!

Preapproval notification format for PayWithMyBank:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
"Preapproval": {
  "ID": 19800,
  "Created": "20190729134913",
  "MethodID": 58,
  "SiteID": 30201,
  "MerchantPreapprovalID": "s2ptest_h-1",
  "RecurringPeriod": 0,
  "PreapprovedMaximumAmount": "20",
  "Currency": null,
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "1 year subscription",
  "Customer": {
    "ID": 2625948,
    "MerchantCustomerID": null,
    "Email": "jdoe@gmail.com",
    "FirstName": "John",
    "LastName": "Doe",
    "Gender": null,
    "SocialSecurityNumber": null,
    "Phone": null,
    "Company": null,
    "DateOfBirth": null
  },
  "BillingAddress": {
    "ID": 520,
    "City": null,
    "ZipCode": null,
    "State": null,
    "Street": null,
    "StreetNumber": null,
    "HouseNumber": null,
    "HouseExtension": null,
    "Country": "US"
  },
  "Status": {
    "ID": 2,
    "Info": null,
    "Reasons": null
  },
  "RedirectURL": null,
  "MethodOptionID": 0,
  "PreapprovedFrequency": null,
  "MandateReference": null,
  "Details": null
  }
}

Response:

204 No Content

The message contains a Preapproval object with an updated Status, which can have the following meanings:

PREAPPROVAL STATUS
ID Info Description
1 Pending The customer needs to confirm the preapproval
2 Open The customer confirmed and you can use the preapproval to initiate recurring payments
4 ClosedByCustomer The preapproval is closed and can no longer be used to initiate recurring payments

PayWithMyBank Preapproval Request

Definition: POST /v1/preapprovals

To initiate a preapproval, you must create a preapproval object. The parameters of the preapproval are sent in the message body as a JSON object. See below an example of a preapproval request for PayWithMyBank (58).

With PayWithMyBank, you can create preapprovals that can allow you to form subsequent recurrent payments. This is the most flexible type and allows the merchant to fully control when to initiate the money transfer(s) between the end user’s account and the merchant’s account (credits or debits). The Preapproval call basically creates a transaction representing the end user’s authorization to use their account for payments on the terms set in the request.

A transaction ID is returned to the merchant within the return URL in the Preapproval response/notification. The merchant must store this transaction ID in the end user’s payment profile to allow future recurrent requests. The amount sent on the initial call defines the maximum aggregate amount that can be captured from the end user’s account across all recurrent calls. A zero-amount value on the Preapproval call removes this upper bound limit. With that setting, the merchant can enable open-ended recurrent scenarios.

For PayWithMyBank preapproval requests CustomerName and CustomerEmail parameters are mandatory in the initial payment request.

Request:

POST https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_h-1",
   "PreapprovedMaximumAmount": 20,
   "Currency": "USD",
   "Description": "1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 58,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "US"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/PWMB/Landing/PreapprovalLanding.aspx?ID=15351&Hash=CD3F91C3DF49E901E91240FA42D89A64",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

GlobalPay Status Codes

List of transaction status IDs
Status ID Name Description Final Status Applicable for
1 Open The transaction is initiated in our system. No Payments / Refunds / Payouts
2 Success The transaction is successful. Yes Payments / Refunds / Payouts
3 Cancelled The payment was cancelled. The payments that can be cancelled are the payments with “Authorized” status or the payments that are cancelled by the customer on the form. Yes Payments
4 Failed The transaction has failed. Yes Payments / Refunds / Payouts
5 Expired The time period the customer had for completing the payment has expired. Yes Payments
9 Authorized The payment was successfully authorized. In the initial request the Capture parameter is sent to false so the responsibility of the capturing the payment is on the merchants side.
The goods can be delivered.
No Payments
13 CaptureRequested The payment was successfully authorized and the capture request was also sent to the provider.
The goods can be delivered.
No Payments
14 Exception The transaction needs manual review from Smart2Pay. No Payments
15 CancelRequested The cancel request has been sent. No Payments
16 Reversed The authorization has been reversed (the money were credited back to the customer account). Yes Payments
19 Disputed The payment is disputed by the customer. No Payments
26 Chargedback The cardholder has won the dispute and has received the money back. Yes Payments
35 PartiallyCaptured The payment is partially captured. Yes Payments

PSD2 and Strong Customer Authentication (SCA)

The Second Payment Services Directive (PSD2), a set of laws and regulations for payment services in the European Union (EU) and the European Economic Area (EEA), has come with a lot of implications for marketplace business models already, and it will expand further more on all companies in Europe that deal with payments, ranging from how to regulate the emergence of Third Party Providers (TPPs) to the need for strong customer authentication (SCA).

Strong Customer Authentication (SCA) will come into effect on 14 September 2019, so there is little time for merchants to start updating their integration to prepare for it. Transactions that don’t follow the new authentication guidelines may be declined by the banks.

Strong Customer Authentication (SCA) has to be applied when all of the conditions below are met:

  • The business is based in the European Economic Area (EEA);
  • The customers are from EEA area;
  • The payment is initiated online by the customer.

SCA requires merchants to integrate into the checkout flow a two-factor authentication that is based on the use of two or more elements categorised as:

  • knowledge (something only the user knows, i.e password);
  • possession (something only the user possesses: i.e.,phone, token, certificate tec.);
  • inherence (something the user is: i.e. fingerprint, Face ID).

For an authentication to meet the criteria of the PSD2, it must combine at least 2 of these 3 factors. To strongly authenticate an online payment, for example, consumers will be required to use their phone (something you own) and authenticate via fingerprint (something you are).

As of September 14, the credit card number alone will no longer be considered as a valid authentication method and additional factors that meet the requirements of PSD2, such as biometric data, need to be added in the authentication process.

The 3D Secure version 1.0 authentication method used for credit card payments is being updated to version 2.0, which is the best measure to meet the above compliance criteria.

Apart from these cases there are a few exemptions to SCA, but keep in mind that banks can choose to not honor these exemptions and you need to be prepared to handle a SCA challenge even if the transactions has been submitted under one of the exemptions.

Below is the list with the most relevant ones. For more detailed information, check out our dedicated section Exemptions to Strong Customer Authentication (SCA).

Exemptions to Strong Customer Authentication (SCA)
Exemption Description
Low Value Small amounts less than 30 EUR: For a transaction of less than 30 EUR and up to 100 EUR accumulated or up to 5 transactions since the last SCA. Beyond 100 EUR or beyond 5 unauthenticated transactions, a new SCA is required. Keep in mind that since the information needed to validate these stipulations is only available to the issuing bank, you will still need to confirm if SCA is required on all transactions that might fall into this exemption category.
Low Risk / TRA Transactional Risk Analysis: SCA can be deactivated for online payments between €30 and €500, depending on the payment providers fraud rates (see table below). There are no low-risk exemptions for transactions over €500. Merchants have to rely on a payment service provider (e.g. an acquirer) to act upon their request. In addition, the test to trigger the exemption rests with whether the PSP satisfies the prescribed conditions, not the merchants themselves. Smart2Pay keeps a very low fraud rate by using state of the art anti-fraud solutions such as RedShield, Machine Learning algorithms and by working with low risk acquiring banks which have very good fraud scores.
MIT Merchant Initiated Transaction (MIT): are payment transactions that are not initiated by the payer but by the payee only and are not subject to strong customer authentication (SCA) to the extent that these transactions are initiated without any interaction or involvement of the payer. MIT transactions are subjected to SCA except when a mandate is signed by the client. For example, SEPA Direct Debits are initiated by the merchant but have a direct debit mandate signed by the end customer. Thus, SCA is not applicable in this case and there are no restrictions to the frequency or the amount (obtained scheme transaction identifier needs to be provided for use in the subsequent transactions).
Trusted Beneficiaries Payment to a trusted beneficiary: Customers can add their preferred online sellers to a list of trusted beneficiaries held by the issuing bank, so that they don’t required to authenticate for each new payment. Please instruct your customers if possible to add your business to the white-list at their bank.
Secure Corporate payments SCA can de deactivated for corporate card payments made through secure processes and protocols initiated by businesses and not available for consumers. Payments that are included in this category are those made through central travel accounts, lodged cards, virtual cards, and secure corporate cards, like the ones used in a corporate travel management system.

Please check out our page again soon where we will keep you posted on any updates regarding 3D Secure version 2.0.

Payout Notification

We will notify you about the new status of the payout to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

You need to respond with HTTP code 204 (No Content)!

Payout notification format:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "ID": 376,
    "Created": "20190507131247",
    "MerchantTransactionID": "s2ptest_j1",
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "",
    "SiteID": 30201,
    "Details": null,
    "Customer": null,
    "BillingAddress": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    }
  }
}

Response:

204 No Content

Get information on a specific Payout

You can get information about a payout by using GET HTTP request.

Definition: GET /v1/payouts/{id}

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://paytest.smart2pay.com/v1/payouts/376
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payout": {
        "ID": 376,
        "Created": "20190507131247",
        "MerchantTransactionID": "s2ptest_j1",
        "Amount": "1000",
        "Currency": "EUR",
        "Description": null,
        "SiteID": 30201,
        "Details": null,
        "Customer": {
            "ID": 335,
            "MerchantCustomerID": "0125",
            "Email": "youremail@email.com",
            "FirstName": "Example",
            "LastName": "Test",
            "Gender": "F",
            "SocialSecurityNumber": "ABCDE1234F",
            "Phone": "0765260000",
            "Company": "S2P",
            "DateOfBirth": "19800519"
        },
        "BillingAddress": null,
        "Status": {
            "ID": 2,
            "Info": "Success",
            "Reasons": null
        }
    }
}

Create a Payout

Definition: POST /v1/payouts

To initiate a payout, you must create a payout object. The parameters of the payout are sent in the message body as a JSON object.

The payment methods that support payouts are: Trustly (29) and Qiwi (1003).

  • For Trustly Payouts(29) you need to send in the request the Customer Bank Account ID parameter.

    A 201 HTTP response (Created) is returned if the payout was correctly initialized.

    Request:

    POST https://paytest.smart2pay.com/v1/payouts
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payout": {
        "MerchantTransactionID": "s2ptest_j1",
        "Amount": 1000,
        "Currency": "EUR",      
        "MethodID": 29,
        "Customer": {    
          "Email": "youremail@email.com"   
        },
        "Details":{
          "CustomerBankAccountID": "3541977722"}
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payout": {
            "ID": 376,
            "Created": "20190507131247",
            "MerchantTransactionID": "s2ptest_j1",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": null,
            "SiteID": 30201,
            "Details": {
                "CustomerBankAccountID": "3541977722"
            },
            "Customer": {
                "ID": 335,
                "MerchantCustomerID": null,
                "Email": "youremail@email.com",
                "FirstName": null,
                "LastName": null,
                "Gender": null,
                "SocialSecurityNumber": null,
                "Phone": null,
                "Company": null,
                "DateOfBirth": null
            },
            "BillingAddress": null,
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": null
            }
        }
    }
  • For Qiwi Payouts all you need is the customer’s phone number and no restrictions regarding an initial payment with the same phone number. This option applies only for customers that have an active Qiwi Wallet Account.

    Request:

    POST https://paytest.smart2pay.com/v1/payouts
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payout": {
        "MerchantTransactionID": "s2ptest_j12",
        "Amount": 10,
        "Currency": "USD",      
        "MethodID": 1003,
        
        "Customer": {    
         "Phone":"+79257836967" 
        }    
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payout": {
        "ID": 511,
        "Created": "20190603111300",
        "MerchantTransactionID": "s2ptest_j12",
        "Amount": "10",
        "Currency": "USD",
        "Description": null,
        "SiteID": 30201,
        "Details": null,
        "Customer": {
          "ID": 207203,
          "MerchantCustomerID": null,
          "Email": null,
          "FirstName": null,
          "LastName": null,
          "Gender": null,
          "SocialSecurityNumber": null,
          "Phone": "+79257836967",
          "Company": null,
          "DateOfBirth": null
          },
        "BillingAddress": null,
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": null
        }
      }
    }

For Qiwi Payouts to be successful the phone number used in the request has to be linked with a Qiwi wallet account, otherwise the payout request will be rejected with the below message:

Request:

POST https://paytest.smart2pay.com/v1/payouts
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "MerchantTransactionID": "s2ptest_j13",
    "Amount": 10,
    "Currency": "USD",      
    "MethodID": 1003,
    
    "Customer": {    
     "Phone":"+79257836965" 
    }    
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 513,
    "Created": "20190603114013",
    "MerchantTransactionID": "s2ptest_j13",
    "Amount": "10",
    "Currency": "USD",
    "Description": null,
    "SiteID": 30201,
    "Details": null,
    "Customer": {
      "ID": 212321,
      "MerchantCustomerID": null,
      "Email": null,
      "FirstName": null,
      "LastName": null,
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": "+79257836965",
      "Company": null,
      "DateOfBirth": null
      },
    "BillingAddress": null,
    "Status": {
      "ID": 4,
      "Info": "Failed",
      "Reasons": [
        {
          "Code": "278",
          "Info": "User does not exists"
        }
      ]
    }
  }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

POST https://paytest.smart2pay.com/v1/payouts
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "MerchantTransactionID": "s2ptest_j2",
    "Amount": 1000,
    "Currency": "EUR",      
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "Details":{
      "CustomerBankAccountID": "3541977722"}
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Payout": {
        "ID": 0,
        "Created": null,
        "MerchantTransactionID": "s2ptest_j2",
        "Amount": "1000",
        "Currency": null,
        "Description": null,
        "SiteID": 30201,
        "Details": {
            "CustomerBankAccountID": "3541977722"
        },
        "Customer": {
            "MerchantCustomerID": null,
            "Email": "youremail@email.com",
            "FirstName": null,
            "LastName": null,
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": null,
        "Status": {
            "ID": null,
            "Info": null,
            "Reasons": [
                {
                    "Code": "1",
                    "Info": "Missing parameter - MethodID"
                }
            ]
        }
    }
}

Disputes Details

Go to Disputes tab from the dashboard and use the search filters to find a specific dispute. After you have found the transaction you have been looking for, using the search filters, just double click on it to see specific details of that dispute.

A new window will open containing the general details for that Dispute ID and also providing details about specific sections, like: Reporting, Reason Codes and Initial Payment.

The dashboard Dispute Details allows the user to always find specific information in order to be informed and keep track of his day-to-day operations and disputes.

General provides detailed information for the following fields: ID of the dispute, Initial Payment ID, Input Date Time, Merchant ID, Merchant Site ID, Method ID, Merchant Alias, Merchant Site Alias, Method Name, Amount, Currency and Status.

32

Reporting provides detailed information for the following fields: Notification Date Time and Last Notified Status.

32

Reason Codes provides detailed information for the following fields: Reason Code and Reason.

32

Initial payment provides detailed information for the following fields: ID, Merchant Transaction ID, Originator Transaction ID, Input Date Time, Amount, Currency, Status, Available Amount, Method ID, Method Name and Country.

32

Disputes List

Access the Disputes tab in order to see and verify your disputes. Here you will find a complete list of all of your payments that are disputed by the customer. You have the possibility to search for a specific dispute using different search filters, to see the details of the disputes, and to export your disputes into an Excel file.

32

Search filters

When you access the Disputes tab, the Search Filters section is expanded. In order to collapse it just click the arrow on the right of the screen.

You can search disputes by ID (the dispute id in the GlobalPay system), Initial Payment ID, Method, Amount, Currency, Status, Interval (from – to) and Site Alias.

32

Disputes Details

After you have found the transaction you’ve been looking for, using the search filters, just click on it to see the specific details of that dispute.

A new window will open containing the general details for that disputes ID and also providing details about specific sections, like: Reporting, Reason Codes, Initial Payment.

66

Export transactions

The list of disputes can be exported (filtered or not) to an .xls file. Click on the Export to EXCEL button at the end of the list of payments.

32

The downloaded file contains the following information: ID, Input Date/Time, Payment ID, Originator Transaction ID, Amount, Currency, Status, Status ID, Method, Method ID, Site ID, Site Alias, Reason Code and Reason.

32

Preapprovals Details

Go to Preapprovals tab from the dashboard and use the search filters to find a specific preapproval. After you have found the transaction you have been looking for, using the search filters, just double click on it to see specific details of that preapproval.

A new window will open containing the general details for that Preapproval ID and also providing details about all the payments associated with that preapproval.

The dashboard Preapprovals Details allows the user to always find specific information in order to be informed and keep track of his day-to-day operations and preapprovals.

General provides detailed information for the following fields: ID of the preapproval, Merchant Preapproval ID, Status, Method ID,Site ID, Site Alias, Merchant Alias, Merchant ID, Input Date Time, Description, Details, Maximum Amount, Currency, Method Option ID, Frequency, Mandate Reference.

32

Payments contains a list of all the payments associated with that preapproval and provides detailed information for the payment’s following fields: Payment ID, Merchant Transaction ID, Amount, Currency, Status, Method, Root Provider Transaction ID, Site, Country.

32

Preapprovals List

Access the Preapprovals tab in order to see and verify your preapprovals. Here you will find a complete list of all of your preapprovals. You have the possibility to search for a specific preapproval using different search filters, to see the details of the preapproval and all the payments associated with the preapproval.

32

Search filters

When you access the Preapprovals tab, the Search Filters section is expanded. In order to collapse it just click the arrow on the right of the screen.

You can search preapprovals by ID (the preapproval id in the GlobalPay system, a unique number that identifies the preapproval in the GlobalPay system; you will need to store this id in order to initiate recurring payments.), Merchant Preapproval ID (the preapproval id in your system), Status, Method, Site Alias and Interval (from – to).

32

Preapprovals Details

After you have found the transaction you’ve been looking for, using the search filters, just click on it to see the specific details of that preapproval.

A new window will open containing the general details for that Preapproval ID and also providing details about all the payments associated with that preapproval.

32

Capture scenarios for PostFinance Card

 

Capture Scenarios Response Status Description Notification Status Description

The transaction has been fully captured.

Only payments with “Authorized” status (9) can be captured.
Intermediary Status: 13 Capture Requested Final Notification Status: 2 Success

The payment has been partially captured.

Only payments with “Authorized” status can be partially captured. The payment has been sent out to be partially captured, but the payment gateway has not yet confirmed that the payment is successful.
Intermediary Status: 13 Capture Requested Final Notification Status: 35 Partially Captured
Capture Failed Scenarios Return Code Description

Retry Capture

This happens when the request timeouts at Provider; a new capture request has to be initiated.
Return Code: 157 Unable to capture transaction

The transaction could not be captured.

The transaction is not in an Authorized status (it has already been fully Captured or Partially Captured).
Return Code: 17 Payment is invalid

For a complete list of all the possible Return Code IDs go to our section GlobalPay Return Codes.

See the request – response examples for the above possible scenarios:

  • Success Status

    A payment can only be captured if it has an Authorized status. Once the payment has an Authorized status (9), you can capture either the full amount or a partial amount of the initial authorized amount for the transaction.

    A 200 HTTP response (OK) is returned if the request was completed successfully.

    Full capture means you capture the entire authorized amount for the initial transaction.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4424180/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4424180,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190320121124",
            "MerchantTransactionID": "PostFinance_55EMI",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190320121338",
            "Customer": null,
            "BillingAddress": {
                "ID": 7808,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "CH"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": null
            },
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
        }
    }
    

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payment": {
        "ID": 4424180,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190320121124",
        "MerchantTransactionID": "PostFinance_55EMI",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "CHF",
        "CapturedAmount": "1000",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "",
        "MethodID": 1129,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30151,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
          "ID": 7808,
          "City": null,
          "ZipCode": null,
          "State": null,
          "Street": null,
          "StreetNumber": null,
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "CH"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 10,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
      }
    }
    
  • Partially Captured Status

    Partial capture means you have the possibility to capture a smaller amount than the one from the initial authorized transaction. Partial capture is used when you have sent at least part of the order to the consumer and want to capture the amount for the item(s) that have been shipped.

    You can perform only one partial capture for an authorized transaction with the limitation that the amount of the partial capture to be smaller or equal than the initial authorized amount.

    Specify only the captured amount parameter in the query string, in order to partially capture the payment, like in the below example:

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4424180/capture?amount=500
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4424180,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190320121124",
            "MerchantTransactionID": "PostFinance_55EMI",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190320121338",
            "Customer": null,
            "BillingAddress": {
                "ID": 7808,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "CH"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": null
            },
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
        }
    }
    

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk={
      "Payment": {
        "ID": 4424180,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190320121124",
        "MerchantTransactionID": "PostFinance_55EMI",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "CHF",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "",
        "MethodID": 1129,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30151,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
          "ID": 7808,
          "City": null,
          "ZipCode": null,
          "State": null,
          "Street": null,
          "StreetNumber": null,
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "CH"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
          "ID": 35,
          "Info": "PartiallyCaptured",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 10,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
      }
    }
    
  • Return Code: 157 – Unable to capture transaction

    The transaction could not be captured. Retry Capture. This happens when the request timeouts at Provider.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4426277/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4426277,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190322135942",
            "MerchantTransactionID": "s2ptest_a3",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": "test test",
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190322140025",
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": [
                    {
                        "Code": "157",
                        "Info": "Unable to capture transaction"
                    }
                ]
            },
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }
  • Return Code: 17 – Payment is invalid

    The transaction could not be captured. The transaction is not in an Authorized status. You can receive this response when the payment you want to Capture is not Authorized or when the payment has already been Captured.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4426219/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8{
        "Payment": {
            "ID": 4426219,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190322125640",
            "MerchantTransactionID": null,
            "OriginatorTransactionID": null,
            "Amount": null,
            "Currency": null,
            "CapturedAmount": null,
            "ReturnURL": null,
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": null,
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": [
                    {
                        "Code": "17",
                        "Info": "Payment is invalid - 4426219"
                    }
                ]
            },
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }

PayTM Test Data

For PayTM payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PayTM – Test Payment Flow

  1. The customer enters his Email Address, Name, Permanent account number (PAN) and his address including Street, Street Number and City. Please note that for India the CustomerSocialSecurityNumber parameter consists of PAN. For more information about the PAN please click here. 1 Enter customer details
  2. The customer is redirected to the PayTM Wallet where he needs to add the mobile number registered for the wallet account.1 Login
  3. The Customer checks the payment resume and confirms the payment by clicking on the Pay now button.1 Confirm payment
  4. Payment is processed. Once confirmed, the customer is routed back to order confirmation. The customer receives a message that the payment has been completed correctly.1 Process payment
  5. Upon completion of the payment flow the customer is redirected back to your ReturnURL.1 Return page when the redirection status is a success

PostFinance e-finance Test Data

For PostFinance e-finance payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PostFinance e-finance Payment Flow

  1. The customer enters his e-finance number or usernames and password. For customers with several users (e.g. partner account): they need to enter their user ID as well. He confirms by using Next button.

    1 Login details

  2. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

PostFinance Card Test Data

For PostFinance Card payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PostFinance Card Payment Flow

  1. The customer enters his ID number and continues the payment.

    1 ID Number

  2. The customer enters his Card Number. He finalizes the payment by using the Pay button.

    1 Card number

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Smart2Pay Android SDK Instructions for Credit Cards (Java)

The interaction flow is described next:

  1. Upon order initiation form the customer
  2. Your server asks our server for a temporary API Key at entry point api/authorization/apikey:

    Request:

    POST https://securetest.smart2pay.com/v1/authorization/apikey
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
  3. Our server responds with a temporary API Key:

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "ApiKey": {
        "Value": "MzAwMDc6M2FkODVhYzctNjhlNS00MTA2LTliNjctNTg3MmM1ZmI2ZDNiLTYzMzA=",
        "Created": "20181206141407",
        "LifeTime": 30,
        "AccessCounterLimit": 10,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }
  4. The temporary API Key must be passed to the app.

  5. From the app you collect the credit cards details from which you build a CardAuthenticationRequest object, together with the temporary API key obtained in the previous step. Set callback functions to handle Success and Failure cases.

    CardAuthenticationRequest cardAuthenticationRequest = new CardAuthenticationRequest("Basic " + apiKey, true);
    
    HashMap card = new HashMap();
    card.put("HolderName", ((EditText)findViewById(R.id.e_cardholder_name)).getText().toString());
    card.put("Number", ((EditText)findViewById(R.id.e_cc_number)).getText().toString());
    card.put("ExpirationMonth", ((EditText)findViewById(R.id.e_exp_month)).getText().toString());
    card.put("ExpirationYear", ((EditText)findViewById(R.id.e_exp_year)).getText().toString());
    card.put("SecurityCode", ((EditText)findViewById(R.id.e_cvv)).getText().toString());
    
    cardAuthenticationRequest.setRequestBody(CCAuthenticateRequestBodyBuilder.getBody(card));
    cardAuthenticationRequest.setCallback((new CardAuthenticationRequest.Callback() {
        public void onSuccess(@NonNull final String creditCardToken) {
            // Authorization was successful!
            // Send it to your server and initiate a transactions via REST API: https://docs.smart2pay.com/category/direct-card-processing/one-click-payment/
            Log.d("TokenForCreditCard", creditCardToken);
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Credit Card Token:" + creditCardToken);
                }
            });
        }
    
        public void onFailure() {
            Log.w(TAG,"Card Authentication request failed.");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Card Authentication request failed.");
                }
            });
        }
    }));
    cardAuthenticationRequest.enqueue();
    
  6. Our SDK calls our server with these details.
  7. The server responds with a token to our SDK.
  8. Our SDK passed the token back to your APP via the callback function setup in step 5.
  9. The order can now be submitted from the app to your server together with the token
  10. A credit card transaction using token is now initiated from your server. For more details go to: Recurring Card Payments section. You can store the token on your server for subsequent purchases.
  11. Our server responds to your server with the Authorization result. Upon a successful result you can release the goods or services.
  12. You pass the payment result to the app.

SDK is now fully functional in your app!

Smart2Pay iOS SDK Instructions (Swift)

Now that you have imported the Smart2Pay.SDK package into your app, you need to follow the below steps in order to set up the Mobile SDK for iOS in Swift language.

  1. To get back to the app after doing a payment we need to set an URL Scheme.

    Select the Project icon again in your file hierarchy – make sure you are in the Info tab – URL Types.

    Fold it open and click the + button. You only need to set URL Schemes field. For example, you can use your bundle identifier. This ensures that there’s no other app that uses this URL Scheme.

    We’re all set to make a payment now!

  2. Create a payment from the data you’ve attained from the API.

    
    ```
    Let payment = Payment(id: id)
    payment.amount = 100 // This is in cents
    payment.currency = "CNY" // Use the three letter abbreviation
    payment.type = .ALIPAY // or .WECHAT 
    payment.delegate = this // The current view controller with PaymentManagerDelegate implementation
    let paymentManager = PaymentManager("urlscheme from step 4")
    paymentManager.pay(payment)
    ```
    
  3. Make sure the view controller uses the delegate implementation:

    PaymentManager.PaymentManagerDelegate

    For example, your view controller could look like this:

    
    `
    class ViewController: UIViewController, PaymentManagerDelegate {
    `
    

    To get the callbacks from the Payment Manager you need to add these two functions:

    
    ```
    func onPaymentSuccess(_ payment: Payment, _ body: [String: Any]) {
    }
        
    func onPaymentFailure(_ payment: Payment) {
    }
    ```
    

    The information needed is inside the payment. This is the structure of a Payment:

    
    ```
    class Payment {
       enum PaymentProvider: Int {
            case NONE = 0
            case ALIPAY = 24
            case WECHAT = 1066
        }
        var id: Int = 0
        var type = PaymentProvider.NONE
        var amount: Int = 0
        var currency: String = ""
        var instructions: String = "" 
        var delegate: PaymentManagerDelegate?
    }
    ```
    

SDK is now fully functional in your app!

Smart2Pay iOS SDK Installation

You need to follow the below steps to build an in-app payment flow fully functional using Smart2Pay SDK in your iOS app using Swift.

  1. Download the Smart2Pay.framework.
  2. Import the framework into your project by either dragging it into the project or go to File | Add files to “project name”.
  3. Add the framework to the Embedded Binaries. Select the Project icon in your file hierarchy – make sure you are in the General tabEmbedded Binaries.

    There are three scenarios possible do the one that applies to you:

    • If you don’t see it in “Embedded Binaries” and don’t see it in the “Linked Frameworks and Libraries”, just click the + on “Embedded Binaries” and select the Smart2Pay.framework.
    • If you see it in “Linked Frameworks and Libraries” but not in “Embedded Binaries”, you should first remove it from “Linked Frameworks and Libraries” and click the + on “Embedded Binaries” and select the Smart2Pay.framework. This will automatically add it to both.
    • If you see it in both “Embedded Binaries” and “Linked Frameworks and Libraries”, you don’t need to do anything.

Now that the SDK is in the app we can actually use it in the code. Continue with setting up the SDK: Smart2Pay iOS SDK Instructions (Swift).

Mobile SDK – Cards

Besides Alipay and WeChat, our Mobile SDK can be used for in-app purchases using Credit Cards. The advantage of using our SDK is that the credit card details never reach your server, simplifying to a minimum the PCI requirements you must meet.

The interaction flow is described next:

  1. Upon order initiation form the customer
  2. Your server asks our server for a temporary API Key at entry point api/authorization/apikey:

    Request Model:

    POST https://securetest.smart2pay.com/v1/authorization/apikey
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
  3. Our server responds with a temporary API Key:

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "ApiKey": {
        "Value": "MzAwMDc6M2FkODVhYzctNjhlNS00MTA2LTliNjctNTg3MmM1ZmI2ZDNiLTYzMzA=",
        "Created": "20181206141407",
        "LifeTime": 30,
        "AccessCounterLimit": 10,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }
  4. The temporary API Key must be passed to the app.

  5. From the app you collect the credit cards details from which you build a CardAuthenticationRequest object, together with the temporary API key obtained in the previous step. Set callback functions to handle Success and Failure cases.

    CardAuthenticationRequest cardAuthenticationRequest = new CardAuthenticationRequest("Basic " + apiKey, true);
    
    HashMap card = new HashMap();
    card.put("HolderName", ((EditText)findViewById(R.id.e_cardholder_name)).getText().toString());
    card.put("Number", ((EditText)findViewById(R.id.e_cc_number)).getText().toString());
    card.put("ExpirationMonth", ((EditText)findViewById(R.id.e_exp_month)).getText().toString());
    card.put("ExpirationYear", ((EditText)findViewById(R.id.e_exp_year)).getText().toString());
    card.put("SecurityCode", ((EditText)findViewById(R.id.e_cvv)).getText().toString());
    
    cardAuthenticationRequest.setRequestBody(CCAuthenticateRequestBodyBuilder.getBody(card));
    cardAuthenticationRequest.setCallback((new CardAuthenticationRequest.Callback() {
        public void onSuccess(@NonNull final String creditCardToken) {
            // Authorization was successful!
            // Send it to your server and initiate a transactions via REST API: https://docs.smart2pay.com/category/direct-card-processing/one-click-payment/
            Log.d("TokenForCreditCard", creditCardToken);
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Credit Card Token:" + creditCardToken);
                }
            });
        }
    
        public void onFailure() {
            Log.w(TAG,"Card Authentication request failed.");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Card Authentication request failed.");
                }
            });
        }
    }));
    cardAuthenticationRequest.enqueue();
    
  6. Our SDK calls our server with these details.
  7. The server responds with a token to our SDK.
  8. Our SDK passed the token back to your APP via the callback function setup in step 5.
  9. The order can now be submitted from the app to your server together with the token
  10. A credit card transaction using token is now initiated from your server. For more details go to: Recurring Card Payments section. You can store the token on your server for subsequent purchases.
  11. Our server responds to your server with the Authorization result. Upon a successful result you can release the goods or services.
  12. You pass the payment result to the app.

Roles Administration

The first user created for a merchant (the one created from the registration form) has a default role assigned. This role (Administrator) has all the access rights existent in the GlobalPay system.

69

Please note that access to this Roles Administration section is only available in production environment!

Click on Add a New Role button and you can create a new role. In the new form that opens, in the General section, you need to provide a role name and a description to the role. 69 In the Access Rights section you can assign access rights for the new role. When finished, click Save and your role will be created. The role you have just created is visible in the grid. You can create as many roles as you like. 70 If you want to remove or add new access rights to a role, or simply modify the name or the description you can click on the Edit button from the grid. And, of course, you can delete the roles you don’t need anymore using the Delete button from the grid.

Users Administration

When entering this section you will see in the grid your user and all the users you have created. These are all the users associated with your Merchant ID.

72

Please note that access to this Users Administration section is only available in production environment!

Click on Add a New User button and you can create a new user. In the new form that opens, in the General section, you need to provide a User Name and a User Email.

In the Roles section you can assign specific roles for the new user. You can assign to the new user one or more of the roles you have previously created.

In the Sites section you can assign specific websites to the new user. When finished, click Save and your new user will be created. Click Save and the new user will be saved and he will receive an email with the password. The User you have just created is visible in the grid. You can create as many users as you like.

Please note that a new user can also be created via API by submitting a POST HTTP request.

If you want to change user name or user email, remove or add roles or update the websites assign to an already created user, you need to click on the Edit button in the grid.

And, of course, you can delete the user accounts that do not serve you anymore using the Delete button from the grid.

74

In the Edit section you can also generate a new password for that specific user. When clicking Generate new password an email will be sent to that user with the new password.

Please be aware that if you assign a user a certain role (that contains specific access rights), that user will only have access to that restricted area defined by that role (and implicitly by the access rights).

Example:

You provide User1 with Role1 that includes NotificationURL-Update access right and Signature-Update access right. This means that User1 will only see two tabs when entering the dashboard: Account and Configuration. And he will have the right to generate a new signature and modify the Notification URL.

An update access right implicitly contains the view access right.

Example:

If the user has only one role that only contains the access right Signature-Update, that user will be able to see the Signature section and update the signature.

If the user has only one role that contains only Signature-view, that user will be able to access the Signature section, but won’t be able to update the signature.

Payment Methods

Here you will find a complete list of all the payment methods, you can easily verify the list of payment methods assigned to your merchant account or to request and activate new payment methods of your choice.

When you access the Payment Methods tab you will see a complete list of all the payment methods available for your merchant account. You have the possibility to search for specific payment methods using different search filters and to see the description for each payment method.

You can search for a specific payment method using the search filters available: payment method’s status, name, description, guaranteed status and countries available.

A very important step during the configuration process is setting up your payment methods. In this section you will be able to configure the preferred way to receive your payments and setup your desired payment methods. The payment methods are selected for an account when the account is created, but they can also be changed at any time needed.

There are a few possible actions available, in order for you to have a better management over your merchant account, that are explained below:

  • Request a new payment method:

    Using the first search filter from the top of the page, choose Can Request option from the dropdown list. A list of all the available payment methods that you can request for your account will appear.

    Once you find the desired payment method, click the “+” Request sign in front of it to add it to your account,

    A confirmation message will be displayed.

    After you have requested the payment method, you need to wait for Smart2pay approval of the payment method. Also, you can check the list of all your requested payment methods by using the first search filter from the top of the page. Choose Approval in Progress option from the dropdown list and a list of all your requested payment methods for your account will appear.

  • Activate a payment method:

    Using the first search filter from the top of the page, choose Can Activate option from the dropdown list. A list of all the payment methods assigned to your account that you can activate will appear.

    Once you find the desired payment method, click the Activate option in front of it to activate it.

    A confirmation message will be displayed.

    You need to wait for Smart2pay approval for the activation of the payment method. Also, you can check the list of all your payment methods that are waiting activation by using the first search filter from the top of the page. Choose Activation in Progress option from the dropdown list and a list of all your payment methods waiting activation will appear.

  • Deactivate a payment method:

    Using the first search filter from the top of the page, choose My Methods option from the dropdown list. A list of all the payment methods activated for your account will appear.

    If you want to deactivate a specific payment method, click the Deactivate option in front of it.

    A confirmation message will be displayed.

  • Ask for availability of a payment method:

    For some payment methods you need to ask our support team for more details regarding its availability. You can check the list of all the payment methods that need further guidance from our support team by using the first search filter from the top of the page. Choose Ask Availability option from the dropdown list and a list of all the payment methods that need further guidance from our support team will appear.

  • Unavailable payment methods:

    Some payment methods may be currently unavailable due to different external factors. You can check the list of all the unavailable payment methods by using the first search filter from the top of the page. Choose Unavailable option from the dropdown list and a list of all the unavailable payment methods will appear.

  • Rejected payment methods:

    If the request of a payment method will have a negative outcome we will let you know. You can check the list of all the rejected payment methods by using the first search filter from the top of the page. Choose Rejected option from the dropdown list and a list of all the rejected payment methods will appear.

iDEAL Implementation guide

iDEAL, one of the most used online banking method in the Netherlands, allows the customer to buy securely on the Internet, directly from his bank account opened at one of the major Dutch banks: ABN AMRO, SNS Bank, RegioBank, Rabobank, Knab, Moneyou, ASN Bank, Triodos Bank, ING, Rabobank, Van Lanschot Bankiers,Knab, Bunq, Moneyou and Handelsbanken.

iDEAL was developed by the Dutch banking community in order to facilitate easier payment for online products and services. iDEAL enables direct and secure real-time online payments between bank accounts of Consumers and iDEAL Merchants. The main characteristics of iDEAL are:

  • Real-time payment through accepted and trusted Internet banking that is already familiar to Consumers;
  • Real-time payment authorisation for the Consumer and real-time confirmation to the Merchant by the Acquiring bank, followed by the irrevocable transfer of funds to the Merchant;
  • Suitability for online delivery (e.g. downloads, mobile top-ups), offline delivery (e.g. goods) and time-critical payments (e.g. airline tickets);
  • Offers the flexibility to make payments for many different purposes (e.g. charitable donations, telephone/e-mail orders).

Please ask support@smart2pay.com for the latest iDEAL Merchant Implementation Guide (MIG) and the necessary operation manuals.

iDEAL Four Party Model

When talking about iDeal transaction, one must know that there are at least four parties involved:

  • The Consumer: buys a product or service online from a Merchant that offers the iDEAL payment method
  • The Merchant: sells products or services online to Consumers
  • The Issuer (the Consumers’ bank): the Consumer executes iDEAL payments in his Internet banking environment – through his Issuer
  • The Acquirer (the Merchant’s bank): the Merchant accepts iDEAL payments – through his Acquirer

Additional parties can be involved in an iDEAL transaction:

  • The Merchant can, for example, use a Payment Service Provider (PSP) to establish the connection with its Acquiring bank. When this PSP receives/collects the payments before they are paid to the Merchant, this is called a “Collecting PSP” (CPSP). In this case the Collecting PSP acts as the Merchant for the purpose of the iDEAL payments and holds the iDEAL contract with the Acquiring bank on behalf of one or multiple other Merchants.
Issuer Selection List Presentation

To ensure that the Consumer experience of an iDEAL transaction is consistent and recognizable through all Merchant websites; all Merchants have to comply with certain presentation standards:

  • All Issuers in the DirectoryResponse (to be collected at least monthly) have to be shown in a list (e.g. dropdown list or list of radio buttons) in alphabetic order and exactly as presented in the DirectoryResponse message.
  • The list should be accompanied by the instruction phrase “Kies uw bank” (UK: “Choose your bank”). In case of an HTML SELECT, the first element in the list states this instruction phrase and is selected by default (to prevent accidental Issuer selection).
  • It is not allowed to exclude or grey out any active Issuers from the Issuer list. In case of a new Issuer, the Issuer list should be updated wihtin one month (preferably earlier).
  • It is recommended to configure the HTML “value” field of the items in the list box to be the issuerID (BIC) of the corresponding Issuer, because this value is used in subsequent messages (TransactionRequest).
  • The Merchant may preselect an Issuer only to allow for an improved user experience (e.g. if the Consumer has previously initiated an iDEAL payment with a specific Issuer). The Consumer must however always be offered the possibility to alter the preselected Issuer.

An example of a correct presentation of the Issuer selection list is shown in the figure:

iDEAL banners and logo’s

Merchants that want to use a banner on their website to promote iDEAL can download the most recent banners at http://www.ideal.nl/en/payee/logos-banners/. These banners need to be installed only once, since the URL will always refer to the latest version of the banner containing the right logos of the participating Issuing banks.

The iDEAL logo must be used by anyone who offers iDEAL as a payment method, informing customers from the beginning that they can pay with iDEAL.

The iDEAL logo may only be used in the provided form and colour. The use of other colours is not permitted.

For more information and instructions for using the iDEAL logo, checkout the manual iDEAL logo.

POLi Test Data (Australia)

In order for you to test POLi payment method successfully, please use the below test data.

POLi Test Data
Data Value
User DemoShopper
Password DemoShopper

POLi Payment Flow (Australia)

  1. The Customer selects his Bank from the list and proceeds with the payment.

    1 Select bank

  2. The Customer enters the login details. He must fill the form with his Username and password and click the Login button.

    1 Login details

  3. The Customer needs to select the bank account he wants to transfer money from and click the Continue button.

    1 Select bank account

  4. The customer is redirected to the provider’s confirmation page where he sees the payment summary and details. He completes the transaction by clicking on the Confirm button.

    1 Transaction confirmation

  5. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Alipay Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for Alipay method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

For Alipay payments only the following Articles parameters are mandatory to be sent in the request, the rest of them are optional:

  • Name – Article’s name;
  • Quantity – The number of products.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request: 

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h31",
    "Amount": "100",
    "Currency": "CNY",      
    "MethodID": 24,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "BillingAddress": {
      "Country": "CN"
      },        
    "Articles": [
      { 
      "Name": "TEST",
      "Quantity": 1
      }
    ]
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4201852,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181120122556",
        "MerchantTransactionID": "s2ptest_h31",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "CNY",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "MethodID": 24,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": "20181120122556",
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": [
            {
                "MerchantArticleID": null,
                "Name": "TEST",
                "Quantity": 1,
                "Price": null,
                "VAT": null,
                "Discount": null,
                "Type": null,
                "TaxType": null,
                "DiscountValue": null
            }
        ],
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}