### Get WSPayForm URL via HTTP POST Request Source: https://docs.wspay.info/wspayform/index This snippet demonstrates how to obtain a WSPayForm URL by sending a JSON request object via HTTP POST to a WSPay endpoint. The request includes shop and transaction details, and the response contains a transaction ID and the payment form URL, or error information if the request fails. Ensure all required fields like 'ShopID', 'ShoppingCartID', and 'TotalAmount' are correctly populated. ```json { "ShopID": "MYSHOP", "ShoppingCartID": "78", "Version": "2.0", "TotalAmount": "17,00", "ReturnURL": "https://myshop.com/success", "ReturnErrorURL": "https://myshop.com/error", "CancelURL": "https://myshop.com/cancel", "Signature": "23455eaf0029bac73613eb00d5242dcf2a5e39fa8d65b26905974dcf61bfbccdaaf0963d79dd73adae117ef108378a2b661faaba5c5ff4c33935fae13fad90a7" } ``` ```json // Successful response { "TransactionId": "LTiEo4U5HEqPl8IFHHbeCA", "PaymentFormUrl": "https://form.wspay.biz/authorization?id=LTiEo4U5HEqPl8IFHHbeCA", "HasErrors": false, "Errors": [] } ``` ```json // Unsuccessful response { "TransactionId": null, "PaymentFormUrl": null, "HasErrors": true, "Errors": [ { "Key": "E00017", "Message": "ReturnURL is mandatory." }, { "Key": "E00018", "Message": "CancelURL is mandatory." } ] } ``` -------------------------------- ### Direct Payment with Token JSON Request and Response (WSPay) Source: https://docs.wspay.info/wspayform/index This snippet demonstrates the JSON request and response structure for initiating a direct payment using a token with WSPay. The request includes all necessary transaction details, while the response provides transaction status and customer information. ```json { "Version": "2.0", "ShopID": "MYSHOPTOK", "ShoppingCartID": "78", "Token": "237038b3-761f-4bf7-a107-a18efa84dde0", "TokenNumber": "2152", "PaymentPlan": "0000", "TotalAmount": "1700", "DateTime": "20190722115807", "CustomerFirstName": "John", "CustomerLastName": "Doe", "CustomerAddress": "Address 10", "CustomerCity": "City", "CustomerZIP": "51000", "CustomerCountry": "HR", "CustomerPhone": "0911111111", "CustomerEmail": "john@doe.com", "Language": "HR", "Signature": "4a2b4246db90ed60eff677a60fd139f50e09c3e19d14a1503921c70780b912cf04fd44a7b3b6bd3376e4089891a2600aef5aade8979ec546a2ad2bac5d7f8daa" } ``` ```json { "WsPayOrderId": "dd9ec33a-0638-47d0-b17a-5de403ae3a3d", "ShoppingCartID": "78", "CustomerFirstName": "John", "CustomerLastName": "Doe", "CustomerAddress": "Address 10", "CustomerCity": "City", "CustomerZIP": "51000", "CustomerCountry": "HR", "CustomerPhone": "0911111111", "CustomerEmail": "john@doe.com", "ECI": null, "XID": null, "CAVV": null, "UCAF": null, "MaskedPan": "377500*******1234", "CreditCardName": "MVISA", "PaymentPlan": "0000", "ApprovalCode": "610990", "ErrorMessage": null, "Approved": "1", "TotalAmount": "1700", "STAN": "38419", "ActionSuccess": "1", "TransactionDateTime": "20181231233202", "Partner": "Pbz", "Signature": "4be89181861d5c9759a5032bbadfd4c4f07c0a90b4001155ddfbabb74512fdcb3927f9226c14d1235a9bcd9a6e4d7723289cb55d3bf2863f9519e32c28c7b3d9" } ``` -------------------------------- ### Transaction Redirects and ReturnURL Parameters Source: https://docs.wspay.info/wspayform/index Details on how customers are redirected after a transaction and the parameters returned to the merchant's ReturnURL. ```APIDOC ## Redirecting Customer to Merchant ### Description After a transaction (successful, unsuccessful, or cancelled), WSPayForm redirects the customer to URLs defined by the merchant (ReturnURL, ReturnErrorURL, CancelURL). The HTTP method used for redirection depends on the `ReturnMethod` parameter. ### ReturnURL Parameters Customer is redirected to `ReturnURL` after a successful transaction. Key parameters include `ApprovalCode`, `Success`, and `Signature`. - **ShoppingCartID** (string) - Unique identification of the transaction in the merchant's system. - **WsPayOrderId** (string) - Unique identification of the transaction in the WSPay system. - **ApprovalCode** (string) - Transaction approval code. Will be empty if the transaction is not successful. - **Success** (integer) - 1 for a successful transaction, empty otherwise. - **Amount** (number) - The amount charged to the customer. - **DateTime** (string) - Date and time of the transaction in `YYYYMMDDHHmmSS` format. - **PaymentType** (string) - Name of the credit card brand or payment type used. - **CreditCardNumber** (string) - Masked credit card number used for the transaction. - **PaymentPlan** (string) - Number of installments and deferred payments chosen by the customer. - **Partner** (string) - The processor that handled the transaction. - **STAN** (string) - Alphanumeric field indicating the transaction sequence. - **ECI** (string) - Electronic Commerce Indicator result of 3D Secure authentication. - **CustomerFirstName** (string) - Customer's first name. - **CustomerSurname** (string) - Customer's last name. - **CustomerAddress** (string) - Customer's street address. - **CustomerCity** (string) - Customer's city. - **CustomerZIP** (string) - Customer's postal code. - **CustomerCountry** (string) - Customer's country (ISO 3166-1 alpha-2 code). - **CustomerPhone** (string) - Customer's phone number. - **CustomerEmail** (string) - Customer's e-mail address. - **Lang** (string) - Language used on WSPayForm. - **ShopPostedPaymentPlan** (string) - Original `PaymentPlan` value sent by the merchant. - **ShopPostedLang** (string) - Original `Lang` value sent by the merchant. - **ShopPostedCreditCardName** (string) - Original `CreditCardName` value sent by the merchant. - **ShopPostedPaymentMethod** (string) - Original `PaymentMethod` value sent by the merchant. - **ErrorMessage** (string) - Will be empty for successful transactions. - **Signature** (string) - Signature generated from `ShopID`, `SecretKey`, `ShoppingCartID`, `Success`, `ApprovalCode` using SHA512. Merchant must validate this signature. ### Response Example (Success) ```json { "ShoppingCartID": "INV12345", "WsPayOrderId": "WSPAY98765", "ApprovalCode": "ABCDEF", "Success": 1, "Amount": 100.50, "DateTime": "20231027103000", "PaymentType": "VI", "CreditCardNumber": "**** **** **** 1234", "PaymentPlan": "1", "Partner": "ProcessorA", "STAN": "123456", "ECI": "05", "CustomerFirstName": "John", "CustomerSurname": "Doe", "CustomerAddress": "123 Main St", "CustomerCity": "Anytown", "CustomerZIP": "12345", "CustomerCountry": "US", "CustomerPhone": "1234567890", "CustomerEmail": "john.doe@example.com", "Lang": "EN", "ShopPostedPaymentPlan": "1", "ShopPostedLang": "EN", "ShopPostedCreditCardName": "Visa", "ShopPostedPaymentMethod": "VI", "ErrorMessage": "", "Signature": "a1b2c3d4e5..." } ``` ``` -------------------------------- ### WSPayForm Optional Parameters Source: https://docs.wspay.info/wspayform/index This section details various optional parameters that can be sent to WSPayForm to customize the user interface and enhance the checkout process. These parameters include language selection, customer information fields, payment plan configuration, and currency details. ```APIDOC ## WSPayForm Optional Parameters Merchants can optionally send parameters to WSPayForm to further customize the UI or speed up the buying process. Some optional parameters can be changed by the customer on WSPayForm, so they are not recommended for order identification; `ShoppingCartID` should be used instead. ### Parameters #### Query Parameters - **Lang** (string) - Optional - Defines the pre-selected language for the WSPayForm user interface. If not sent, the default language defined by WSPay will be used. See documentation for possible values. - **CustomerFirstName** (string) - Optional - Customer's first name. WSPayForm will autofill this field. - **CustomerLastName** (string) - Optional - Customer's last name. WSPayForm will autofill this field. - **CustomerAddress** (string) - Optional - Customer's street address. WSPayForm will autofill this field. - **CustomerCity** (string) - Optional - Customer's city. WSPayForm will autofill this field. - **CustomerZIP** (string) - Optional - Customer's postal code. WSPayForm will autofill this field. - **CustomerCountry** (string) - Optional - Customer's country represented in ISO 3166-1 alpha-2 two-letter code. WSPayForm will autofill this field. - **CustomerPhone** (string) - Optional - Customer's phone number. WSPayForm will autofill this field. - **CustomerEmail** (string) - Optional - Customer's email address. WSPayForm will autofill this field. - **PaymentPlan** (string) - Optional - Defines the payment plan with two subfields. The first subfield is the number of payments, and the second is the grace period (e.g., "0600" for 6 installments, "0602" for 6 installments with a 2-month grace period). If not sent, customers can pay in installments if the merchant has agreed with the bank and their credit card supports it. - **CreditCardName** (string) - Optional - The name of the card brand that must be used for this transaction. Sending this parameter blocks the selection of any other card brand on WSPayForm. See documentation for possible values. - **PaymentMethod** (string) - Optional - The name of the payment method that must be used for this transaction. Sending this parameter blocks the selection of any other payment method on WSPayForm. See documentation for possible values. - **IntAmount** (string) - Optional - An informative amount in a converted currency. Used in conjunction with `IntCurrency`. - **IntCurrency** (string) - Optional - The currency code for the `IntAmount`. Used in conjunction with `IntAmount`. - **ReturnMethod** (string) - Optional - Specifies the HTTP method (GET or POST) used for redirecting the customer to `ReturnURL`, `ReturnErrorURL`, and `CancelURL`. If not sent, GET is used. GET sends transaction info via query parameters; POST sends it via a form. - **CurrencyCode** (string) - Optional - The currency code to be checked against the merchant's configured currency. Must be formatted as an ISO 4217 numeric code. Payment will be unsuccessful if it doesn't match. ### Customer Information Data Rules - **CustomerFirstName**: - Maximum length: 50 characters - No special characters allowed except: `-` - **CustomerLastName**: - Maximum length: 50 characters - No special characters allowed except: `-` - **CustomerAddress**: - Maximum length: 100 characters *Note: If WSPayForm is used without customer input fields and no customer information is sent, shop company data will be used. If customer information is sent, the merchant should validate it before sending to WSPayForm, as credit card processors may decline payments for invalid formats.* ``` -------------------------------- ### Customer Information Parameters Source: https://docs.wspay.info/wspayform/index This section details the validation rules for customer information fields that can be submitted. ```APIDOC ## Customer Information Parameters ### Description Validation rules for various customer data fields used in WSPayForm. ### Parameters #### Request Body (Example) ```json { "CustomerFirstName": "John", "CustomerSurname": "Doe", "CustomerAddress": "123 Main St", "CustomerCity": "Anytown", "CustomerZIP": "12345", "CustomerCountry": "US", "CustomerPhone": "1234567890", "CustomerEmail": "john.doe@example.com" } ``` #### CustomerCity * **Maximum length**: 50 characters * **Allowed characters**: -, . #### CustomerZIP * **Maximum length**: 20 characters * **Allowed characters**: - #### CustomerCountry * Must be an “ISO 3166-1 alpha-2” two-letter country code. #### CustomerPhone * **Maximum length**: 20 characters * **Allowed characters**: Numeric characters only. #### CustomerEmail * **Maximum length**: 254 characters * Must be a valid e-mail address. ``` -------------------------------- ### Submit HTML Form for WSPay Payment Source: https://docs.wspay.info/wspayform/index This snippet provides an HTML form structure that can be submitted to a WSPay URL to initiate a payment. All necessary transaction details are included as hidden input fields. The 'action' attribute of the form should be set to the URL provided by WSPay. This method allows direct redirection of the customer to the payment form. ```html
``` -------------------------------- ### WSPayForm Payment Using Token Source: https://docs.wspay.info/wspayform/index Used for Customer Initiated Transactions (CIT). This method involves redirecting the customer to WSPayForm with pre-filled token details, requiring only CVV entry. ```APIDOC ## WSPayForm Payment Using Token ### Description This method is used for Customer Initiated Transactions (CIT) where the customer is present and initiates the payment using a saved card. It redirects the customer to the WSPayForm with the card number and expiration date pre-filled using provided token information. The customer only needs to enter the CVV to complete the transaction. ### Method POST (Implicitly via redirect) ### Endpoint `/wspay/form` (This is a conceptual endpoint for redirection) ### Parameters (Included in WSPayForm redirect URL) #### Query Parameters - **Token** (string) - Required - Unique identifier representing the tokenized credit card, obtained from a previous tokenization process. - **TokenNumber** (string) - Required - The last 4 digits of the credit card, obtained from a previous tokenization process. - **Other standard WSPayForm parameters** (e.g., ShopID, ShoppingCartID, TotalAmount, etc.) ### Request Example (Conceptual redirect URL with parameters) `https://secure.wspay.com/wspay/form?Token=YOUR_TOKEN&TokenNumber=YOUR_TOKEN_NUMBER&ShopID=MERCHANT_ID&...` ### Response (Customer is redirected to merchant's defined success, failure, or cancel URL after transaction completion on WSPayForm) #### Success Response (200) (Indicated by redirection to merchant's specified URL with transaction status parameters) #### Response Example (Redirection URL parameters indicating success) `https://merchant.com/callback?status=success&order_id=123&...` ``` -------------------------------- ### POST /wspayform Source: https://docs.wspay.info/wspayform/index Obtain a WSPayForm URL by sending a POST request with transaction details. This is the recommended method for redirecting customers to the WSPay payment form. ```APIDOC ## POST /wspayform ### Description Recommended way to redirect customer to WSPayForm is to get WSPayForm URL then redirect customer to given URL. In order to get WSPayForm URL - request object in JSON format must be sent using HTTP POST to endpoint that will be provided by WSPay. ### Method POST ### Endpoint /wspayform ### Parameters #### Request Body - **ShopID** (string) - Required - Your shop identifier. - **ShoppingCartID** (string) - Required - Unique identifier for the shopping cart. - **Version** (string) - Required - API version, typically "2.0". - **TotalAmount** (string) - Required - The total amount of the transaction (e.g., "17,00"). - **ReturnURL** (string) - Required - URL to redirect to upon successful payment. - **ReturnErrorURL** (string) - Required - URL to redirect to if an error occurs during payment. - **CancelURL** (string) - Required - URL to redirect to if the customer cancels the payment. - **Signature** (string) - Required - A signature generated to verify the transaction details. ### Request Example ```json { "ShopID": "MYSHOP", "ShoppingCartID": "78", "Version": "2.0", "TotalAmount": "17,00", "ReturnURL": "https://myshop.com/success", "ReturnErrorURL": "https://myshop.com/error", "CancelURL": "https://myshop.com/cancel", "Signature": "23455eaf0029bac73613eb00d5242dcf2a5e39fa8d65b26905974dcf61bfbccdaaf0963d79dd73adae117ef108378a2b661faaba5c5ff4c33935fae13fad90a7" } ``` ### Response #### Success Response (200) - **TransactionId** (string) - Unique identification of the payment form. - **PaymentFormUrl** (string) - The URL for the WSPay payment form. - **HasErrors** (boolean) - Indicates if there were any errors during the request. - **Errors** (array) - An empty array if the request was successful. #### Response Example (Success) ```json { "TransactionId": "LTiEo4U5HEqPl8IFHHbeCA", "PaymentFormUrl": "https://form.wspay.biz/authorization?id=LTiEo4U5HEqPl8IFHHbeCA", "HasErrors": false, "Errors": [] } ``` #### Error Response (e.g., 400) - **TransactionId** (string) - Null if there was an error. - **PaymentFormUrl** (string) - Null if there was an error. - **HasErrors** (boolean) - True if there were errors. - **Errors** (array) - A list of error objects, each containing a Key and Message. #### Response Example (Error) ```json { "TransactionId": null, "PaymentFormUrl": null, "HasErrors": true, "Errors": [ { "Key": "E00017", "Message": "ReturnURL is mandatory." }, { "Key": "E00018", "Message": "CancelURL is mandatory." } ] } ``` ``` -------------------------------- ### Submit HTML Form to WSPay Source: https://docs.wspay.info/wspayform/index Submit an HTML form directly to the WSPay URL. This method bypasses the need to obtain a URL first and is suitable for direct form submissions. ```APIDOC ## Submit HTML form ### Description Second way to redirect customer to WSPayForm is to submit HTML form inside HTML document to URL provided by WSPay. ### Method POST ### Endpoint [Provided by WSPay] ### Parameters #### Request Body (Form Data) - **ShopID** (string) - Your shop identifier. - **ShoppingCartID** (string) - Unique identifier for the shopping cart. - **Version** (string) - API version, typically "2.0". - **TotalAmount** (string) - The total amount of the transaction (e.g., "17,00"). - **Signature** (string) - A signature generated to verify the transaction details. - **ReturnURL** (string) - URL to redirect to upon successful payment. - **CancelURL** (string) - URL to redirect to if the customer cancels the payment. - **ReturnErrorURL** (string) - URL to redirect to if an error occurs during payment. ### Request Example ```html ``` ``` -------------------------------- ### Direct Payment Using Token API Source: https://docs.wspay.info/wspayform/index Used for Merchant Initiated Transactions (MIT), such as recurring payments. This method involves sending a JSON request directly to WSPay's API endpoint. ```APIDOC ## Direct Payment Using Token API ### Description This API endpoint is used for Merchant Initiated Transactions (MIT) where the merchant processes a payment with a previously saved card without direct customer participation at the time of the transaction. This is suitable for recurring payments, incremental payments, or direct charges. ### Method POST ### Endpoint `[Provided by WSPay]` ### Parameters #### Request Body - **Version** (string) - Required - API version, e.g., "2.0". - **ShopID** (string) - Required - Merchant's unique shop identifier. - **ShoppingCartID** (string) - Required - Unique identifier for the shopping cart or transaction. - **Token** (string) - Required - Unique identifier representing the tokenized credit card, obtained from a previous tokenization process. - **TokenNumber** (string) - Required - The last 4 digits of the credit card, obtained from a previous tokenization process. - **PaymentPlan** (string) - Optional - Payment plan identifier, e.g., "0000". - **TotalAmount** (string) - Required - The total amount of the transaction (e.g., "1700" for 17.00). - **DateTime** (string) - Required - Transaction date and time in `YYYYMMDDHHMMSS` format (e.g., "20190722115807"). - **CustomerFirstName** (string) - Required - Customer's first name. - **CustomerLastName** (string) - Required - Customer's last name. - **CustomerAddress** (string) - Required - Customer's address. - **CustomerCity** (string) - Required - Customer's city. - **CustomerZIP** (string) - Required - Customer's ZIP code. - **CustomerCountry** (string) - Required - Customer's country code (e.g., "HR"). - **CustomerPhone** (string) - Required - Customer's phone number. - **CustomerEmail** (string) - Required - Customer's email address. - **Language** (string) - Optional - Language code for the transaction (e.g., "HR"). - **Signature** (string) - Required - A signature generated based on transaction details for security. ### Request Example ```json { "Version": "2.0", "ShopID": "MYSHOPTOK", "ShoppingCartID": "78", "Token": "237038b3-761f-4bf7-a107-a18efa84dde0", "TokenNumber": "2152", "PaymentPlan": "0000", "TotalAmount": "1700", "DateTime": "20190722115807", "CustomerFirstName": "John", "CustomerLastName": "Doe", "CustomerAddress": "Address 10", "CustomerCity": "City", "CustomerZIP": "51000", "CustomerCountry": "HR", "CustomerPhone": "0911111111", "CustomerEmail": "john@doe.com", "Language": "HR", "Signature": "4a2b4246db90ed60eff677a60fd139f50e09c3e19d14a1503921c70780b912cf04fd44a7b3b6bd3376e4089891a2600aef5aade8979ec546a2ad2bac5d7f8daa" } ``` ### Response #### Success Response (200) - **WsPayOrderId** (string) - Unique WSPay order identifier. - **ShoppingCartID** (string) - The merchant's shopping cart identifier. - **CustomerFirstName** (string) - Customer's first name. - **CustomerLastName** (string) - Customer's last name. - **CustomerAddress** (string) - Customer's address. - **CustomerCity** (string) - Customer's city. - **CustomerZIP** (string) - Customer's ZIP code. - **CustomerCountry** (string) - Customer's country code. - **CustomerPhone** (string) - Customer's phone number. - **CustomerEmail** (string) - Customer's email address. - **ECI** (string/null) - Electronic Commerce Indicator. - **XID** (string/null) - Transaction identifier. - **CAVV** (string/null) - Cardholder Authentication Verification Value. - **UCAF** (string/null) - User Correctness Authorization Field. - **MaskedPan** (string) - Masked primary account number of the card. - **CreditCardName** (string) - Name or type of the credit card (e.g., "MVISA"). - **PaymentPlan** (string) - Payment plan used for the transaction. - **ApprovalCode** (string) - Authorization approval code from the bank. - **ErrorMessage** (string/null) - Error message if the transaction failed. - **Approved** (string) - Indicates if the transaction was approved ('1' for success, '0' for failure). - **TotalAmount** (string) - The total amount of the transaction. - **STAN** (string) - System Trace Audit Number. - **ActionSuccess** (string) - Indicates if the API action was successful ('1' for success). - **TransactionDateTime** (string) - Date and time of the transaction in `YYYYMMDDHHMMSS` format. - **Partner** (string) - Merchant partner identifier. - **Signature** (string) - Signature of the response for verification. #### Response Example ```json { "WsPayOrderId": "dd9ec33a-0638-47d0-b17a-5de403ae3a3d", "ShoppingCartID": "78", "CustomerFirstName": "John", "CustomerLastName": "Doe", "CustomerAddress": "Address 10", "CustomerCity": "City", "CustomerZIP": "51000", "CustomerCountry": "HR", "CustomerPhone": "0911111111", "CustomerEmail": "john@doe.com", "ECI": null, "XID": null, "CAVV": null, "UCAF": null, "MaskedPan": "377500*******1234", "CreditCardName": "MVISA", "PaymentPlan": "0000", "ApprovalCode": "610990", "ErrorMessage": null, "Approved": "1", "TotalAmount": "1700", "STAN": "38419", "ActionSuccess": "1", "TransactionDateTime": "20181231233202", "Partner": "Pbz", "Signature": "4be89181861d5c9759a5032bbadfd4c4f07c0a90b4001155ddfbabb74512fdcb3927f9226c14d1235a9bcd9a6e4d7723289cb55d3bf2863f9519e32c28c7b3d9" } ``` ``` -------------------------------- ### Embedding WSPayForm in an Iframe with iFrameResize Source: https://docs.wspay.info/wspayform/index This snippet shows how to embed the WSPayForm within an HTML iframe and integrate it with the iFrameResize library for automatic resizing. Ensure 'checkOrigin' is set to false for proper WSPayForm functionality within the iframe. The iframeResizer.min.js script must be included separately. ```html ``` ```javascript iFrameResize({ checkOrigin: false }, '#wspayform-iframe'); ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.