{
  "openapi": "3.0.3",
  "info": {
    "title": "MerchantE Host Payments Page API",
    "description": "MerchantE's Hosted Payments Page allows merchants to integrate a secure payment checkout experience into their e-commerce websites. Customers can checkout as guests, create payment accounts, or log in to make a payment.\n\n## Getting Started\n\nBasic requirements:\n- **Web Hosting**: Merchant must have a publicly available website. The Cascading Style Sheet and company logo are hosted by the merchant.\n- **HTML or plain text editor**: Form elements need to be added to existing or new HTML pages.\n- **Merchant Account**: Required to begin processing live transactions.\n- **Submit Final Amount Only**: ME Hosted Checkout will only process the amount sent in the payment_amount field. Shipping charges, local tax, etc. will need to be accommodated before the transaction is submitted.\n\n## Transaction Flow\n\n1. Customer is on merchant's e-Commerce website and clicks Checkout\n2. Customer is redirected to MerchantE Hosted Payment Page\n3. Customer enters payment details and submits payment\n4. If approved: Customer is presented with payment receipt and has the option to return to merchant's website\n5. If declined: Customer is presented with generic payment decline and advised to reach out to issuer for more details\n\n## Integration Steps\n\n1. Obtain a profile ID once the merchant account setup has been completed\n2. Modify or create HTML pages with 'buy now' or 'checkout' links or images\n3. Insert Payment Page URL form in HTML\n4. If necessary, test the form by processing a sale. Ensure that both response URLs function properly.\n\n## Security Settings\n\nThese settings are intended for advanced integrations of ME Hosted Checkout, and will require a server-side programming language to implement properly, such as PHP, JSP, ASP, etc.\n\n- **Security Code**: MD5 hash validation using Profile Key + Security Code + Transaction Amount. When enabled, requests without valid transaction_key will be redirected to cancel_url with resp_text=invalid_tran_key.\n- **HTTP Authentication**: Optional Resp HTTP Username and Password for response URL callbacks using standard HTTP authentication (BASIC + Base64 encoded username:password).\n",
    "version": "1.0.0",
    "contact": {
      "name": "MerchantE Support",
      "url": "https://merchante-solutions.com"
    },
    "license": {
      "name": "Copyright 2023 MerchantE, Inc."
    }
  },
  "servers": [
    {
      "url": "https://cert.hostedpayments.merchante.com/hpp",
      "description": "Certification/Testing Environment"
    }
  ],
  "paths": {
    "/checkout/sign-in": {
      "post": {
        "summary": "Initiate Hosted Payment Page checkout",
        "description": "Redirects customer to MerchantE Hosted Payment Page for checkout. This endpoint accepts form POST data to initiate the payment process.\n\nThe customer will be presented with options to:\n- Checkout as guest (limited view of Hosted Payments)\n- Create a payment account\n- Log in to existing payment account\n",
        "operationId": "initiateCheckout",
        "tags": [
          "Payment Request"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "profile_id"
                ],
                "properties": {
                  "profile_id": {
                    "type": "string",
                    "maxLength": 20,
                    "description": "Merchant Identifier (mandatory). Routes the customer specifically to your payment page.\n",
                    "example": "xxxx4100006000500000001"
                  },
                  "payment_amount": {
                    "type": "string",
                    "maxLength": 12,
                    "format": "numeric",
                    "description": "The amount of the transaction. Only necessary if you have the Custom Amount flag turned off, since in that scenario the payment amount will be sent across from your website to Hosted Payments.\n\n**Important**: If you do not send the amount when the Custom Amount flag is turned off, a hardcoded $0.00 amount will be sent when the customer navigates to the Hosted Payment Page and the customer will not be able to proceed with payment.\n",
                    "example": "500.00"
                  },
                  "invoice_number": {
                    "type": "string",
                    "maxLength": 17,
                    "format": "alphanumeric",
                    "description": "Custom Invoice Number field. Only necessary if you intend on sending an Invoice Number to Hosted Payments. If not, this will automatically be generated once the transaction is processed successfully.\n",
                    "example": "INV-2023-001"
                  },
                  "client_reference_number": {
                    "type": "string",
                    "maxLength": 96,
                    "format": "alphanumeric",
                    "description": "Custom Reference Number. Only necessary if you intend on sending a client reference number from your side to Hosted Payments. If not, this will automatically be generated once the transaction is processed successfully.\n",
                    "example": "REF-12345"
                  },
                  "transaction_key": {
                    "type": "string",
                    "description": "MD5 hash for request validation when Security Code is enabled.\n\n**Calculation**: MD5(Profile Key + Security Code + Transaction Amount)\n\nThe Profile Key is a security code generated by MerchantE. Required only when Security Code security feature is enabled in merchant settings.\n",
                    "example": "5d41402abc4b2a76b9719d911017c592"
                  }
                },
                "x-parameterGroups": [
                  {
                    "name": "Required",
                    "fields": [
                      "profile_id"
                    ]
                  },
                  {
                    "name": "Recommended",
                    "fields": []
                  },
                  {
                    "name": "Others",
                    "fields": [
                      "payment_amount",
                      "invoice_number",
                      "client_reference_number",
                      "transaction_key"
                    ]
                  }
                ]
              },
              "examples": {
                "allOptionalFieldsSent": {
                  "summary": "All optional information sent (Custom Amount OFF)",
                  "description": "In this example where all optional information is sent, the Custom Amount is off. The Invoice and Ref Number fields are sent as part of the request.\n",
                  "value": {
                    "profile_id": "12345678901234567890",
                    "payment_amount": "500.00",
                    "invoice_number": "INV-2023-001",
                    "client_reference_number": "REF-12345",
                    "transaction_key": "5d41402abc4b2a76b9719d911017c592"
                  }
                },
                "noOptionalFieldsSent": {
                  "summary": "No optional information sent (Custom Amount ON)",
                  "description": "In this example where no Optional Information is sent, the Custom Amount is on. The Invoice and Ref Number fields are not sent as part of the request.\n",
                  "value": {
                    "profile_id": "12345678901234567890"
                  }
                },
                "customAmountOn": {
                  "summary": "Custom Amount turned on",
                  "description": "In this example, the Custom Amount is turned on. The Invoice and Ref Number fields are sent as part of the request.\n",
                  "value": {
                    "profile_id": "12345678901234567890",
                    "invoice_number": "INV-2023-001",
                    "client_reference_number": "REF-12345"
                  }
                },
                "customAmountOff": {
                  "summary": "Custom Amount turned off",
                  "description": "In this example, the Custom Amount is turned off. The Invoice and Ref Number fields are not sent as part of the request.\n",
                  "value": {
                    "profile_id": "12345678901234567890",
                    "payment_amount": "500.00"
                  }
                },
                "withSecurityValidation": {
                  "summary": "Request with security validation",
                  "description": "Includes transaction_key for MD5 hash validation using PHP example from documentation",
                  "value": {
                    "profile_id": "12345678901234567890",
                    "payment_amount": "500.00",
                    "transaction_key": "5d41402abc4b2a76b9719d911017c592"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "302": {
            "description": "Redirect to Hosted Payment Page",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                },
                "description": "URL to MerchantE Hosted Payment Page for customer checkout"
              }
            }
          },
          "400": {
            "description": "Invalid request - missing required fields or invalid transaction_key",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                },
                "description": "Redirect to cancel_url with resp_text=invalid_tran_key (when Security Code validation fails)"
              }
            }
          }
        }
      }
    },
    "/webhooks/response-credit-card": {
      "post": {
        "summary": "Credit Card Transaction Response (Webhook)",
        "description": "HTTP POST callback sent to merchant's configured response_url after a credit card transaction has been processed.\n\nYou can set your Response URL in the Advanced URL Management section of the Settings and Configuration Page in the Hosted Payments Admin.\n\nThis is a server-to-server callback and is not directly invoked by the merchant.\n",
        "operationId": "creditCardResponseWebhook",
        "tags": [
          "Response Handling"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PostResponseCreditCard"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merchant acknowledges receipt of transaction response"
          }
        }
      }
    },
    "/webhooks/response-ach": {
      "post": {
        "summary": "ACH Transaction Response (Webhook)",
        "description": "HTTP POST callback sent to merchant's configured response_url after an ACH transaction has been processed.\n\nYou can set your Response URL in the Advanced URL Management section of the Settings and Configuration Page in the Hosted Payments Admin.\n\nThis is a server-to-server callback and is not directly invoked by the merchant.\n",
        "operationId": "achResponseWebhook",
        "tags": [
          "Response Handling"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PostResponseACH"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merchant acknowledges receipt of transaction response"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PostResponseCreditCard": {
        "type": "object",
        "description": "HTTP POST response sent to merchant's response_url once a transaction has been approved.\n\nYou can set your Response URL in the Advanced URL Management sections of the Settings and Configuration Page in the Hosted Payments Admin section.\n\nIt is not necessary to use response data, though it can be helpful to store transaction data, or for integration efforts.\n",
        "x-parameterGroups": [
          {
            "name": "Common",
            "fields": [
              "resp_code",
              "resp_text",
              "tran_id",
              "tran_amount",
              "tran_date"
            ]
          },
          {
            "name": "When Provided",
            "fields": [
              "auth_code",
              "card_id",
              "hpp_tran_id",
              "invoice_number",
              "client_ref_number"
            ]
          },
          {
            "name": "Other Fields",
            "fields": [
              "acct_number",
              "exp_date",
              "billing_address",
              "billing_zip",
              "currency_code",
              "tran_type",
              "retrieval_ref_number"
            ]
          }
        ],
        "properties": {
          "tran_type": {
            "type": "string",
            "description": "The transaction type from the original request.",
            "example": "Sale"
          },
          "tran_amount": {
            "type": "string",
            "description": "The amount of the transaction.",
            "example": "500.00"
          },
          "invoice_number": {
            "type": "string",
            "description": "Identical to the request field of the same name.",
            "example": ""
          },
          "currency_code": {
            "type": "string",
            "description": "Currency code. Defaults to 840 – USD.",
            "default": "USD",
            "example": "USD"
          },
          "client_ref_number": {
            "type": "string",
            "description": "Identical to the request field of the same name.",
            "example": ""
          },
          "acct_number": {
            "type": "string",
            "description": "Truncated card or bank account number.",
            "example": "411111XXXXXX1111"
          },
          "exp_date": {
            "type": "string",
            "description": "Cardholder expiration date.\n\nFormat: MMYY\n",
            "example": "1122"
          },
          "billing_address": {
            "type": "string",
            "description": "Street address entered by the cardholder during checkout.",
            "example": "123"
          },
          "billing_zip": {
            "type": "string",
            "description": "ZIP Code entered by the cardholder during checkout.",
            "example": "12345"
          },
          "retrieval_ref_number": {
            "type": "string",
            "description": "12-digit MerchantE generated reference number.",
            "example": ""
          },
          "auth_code": {
            "type": "string",
            "description": "Authorization code provided by the issuing bank.",
            "example": "T9939 H"
          },
          "resp_code": {
            "type": "string",
            "description": "At this time, resp_code will always be 000 indicating an approved sale.",
            "example": "000"
          },
          "resp_text": {
            "type": "string",
            "description": "A textual response for the transaction result.",
            "example": "ApprovalT9939H"
          },
          "tran_id": {
            "type": "string",
            "description": "Transaction identifier.",
            "example": "e0266d9ceaf234dd99427aebe1a13393"
          },
          "tran_date": {
            "type": "string",
            "description": "Timestamp of the transaction.\n\nFormat: MM/DD/YYYY HH:MM:SS AM/PM\n",
            "example": "Fri Mar 27 17:42:42 UTC 2020"
          },
          "card_id": {
            "type": "string",
            "description": "The returned value is the token for the card which was stored.",
            "example": ""
          },
          "hpp_tran_id": {
            "type": "string",
            "description": "Hosted Payment Page transaction identifier.",
            "example": "1971"
          }
        },
        "example": {
          "tran_date": "Fri Mar 27 17:42:42 UTC 2020",
          "acct_number": "411111XXXXXX1111",
          "tran_amount": "500.00",
          "tran_type": "Sale",
          "billing_address": "123",
          "tran_id": "e0266d9ceaf234dd99427aebe1a13393",
          "currency_code": "USD",
          "auth_code": "T9939 H",
          "resp_text": "ApprovalT9939H",
          "client_ref_number": "",
          "retrieval_ref_number": "",
          "hpp_tran_id": "1971",
          "billing_zip": "12345",
          "resp_code": "000",
          "exp_date": "1122",
          "invoice_number": ""
        }
      },
      "PostResponseACH": {
        "type": "object",
        "description": "HTTP POST response sent to merchant's response_url after ACH transaction",
        "x-parameterGroups": [
          {
            "name": "Common",
            "fields": [
              "resp_code",
              "resp_text",
              "tran_id",
              "amount"
            ]
          },
          {
            "name": "When Provided",
            "fields": [
              "ref_num",
              "cust_name"
            ]
          },
          {
            "name": "Other Fields",
            "fields": [
              "auth_type",
              "account_type",
              "ip_address",
              "ach_request",
              "transaction_type",
              "account_num",
              "profile_key",
              "profile_id",
              "transit_num"
            ]
          }
        ],
        "properties": {
          "auth_type": {
            "type": "string",
            "description": "Authentication type",
            "example": "WEB"
          },
          "amount": {
            "type": "string",
            "description": "Transaction amount",
            "example": "500.00"
          },
          "account_type": {
            "type": "string",
            "description": "Account type (S=Savings, C=Checking)",
            "example": "S",
            "enum": [
              "S",
              "C"
            ]
          },
          "tran_id": {
            "type": "string",
            "description": "Transaction identifier",
            "example": "1991"
          },
          "ip_address": {
            "type": "string",
            "description": "IP address of transaction origin",
            "example": "127.0.0.1",
            "format": "ipv4"
          },
          "ach_request": {
            "type": "string",
            "description": "ACH request type",
            "example": "SALE"
          },
          "transaction_type": {
            "type": "string",
            "description": "Transaction type",
            "example": "H"
          },
          "ref_num": {
            "type": "string",
            "description": "Reference number",
            "example": ""
          },
          "resp_text": {
            "type": "string",
            "description": "Response text",
            "example": "ACH IP Address Invalid"
          },
          "account_num": {
            "type": "string",
            "description": "Truncated account number",
            "example": "XXXXXX4738"
          },
          "profile_key": {
            "type": "string",
            "description": "Merchant profile key",
            "example": "yyyy"
          },
          "profile_id": {
            "type": "string",
            "description": "Merchant profile identifier",
            "example": "xxxx4100006000500000001"
          },
          "transit_num": {
            "type": "string",
            "description": "Truncated routing/transit number",
            "example": "XXXXX0399"
          },
          "resp_code": {
            "type": "string",
            "description": "Response code",
            "example": "811"
          },
          "cust_name": {
            "type": "string",
            "description": "Customer name",
            "example": "name"
          }
        },
        "example": {
          "auth_type": "WEB",
          "amount": "500.00",
          "account_type": "S",
          "tran_id": "1991",
          "ip_address": "127.0.0.1",
          "ach_request": "SALE",
          "transaction_type": "H",
          "ref_num": "",
          "resp_text": "ACH IP Address Invalid",
          "account_num": "XXXXXX4738",
          "profile_key": "yyyy",
          "profile_id": "xxxx4100006000500000001",
          "transit_num": "XXXXX0399",
          "resp_code": "811",
          "cust_name": "name"
        }
      },
      "SecurityHashComponents": {
        "type": "object",
        "description": "Components used to generate MD5 hash for transaction_key security validation.\n\nTo validate a request, create an MD5 hash of the following fields (in this order):\n1. Profile Key - A security code generated by MerchantE\n2. Security Code\n3. Transaction Amount\n\nThe result of this MD5 hash then needs to be sent in the field transaction_key.\n",
        "required": [
          "profile_key",
          "security_code",
          "transaction_amount"
        ],
        "properties": {
          "profile_key": {
            "type": "string",
            "description": "A security code generated by MerchantE",
            "example": "EslVInonBTrSMXZzQapRPPQQwVvjAGgi"
          },
          "security_code": {
            "type": "string",
            "description": "The Security Code is a password used to secure requests to ME Hosted Checkout",
            "example": "test123"
          },
          "transaction_amount": {
            "type": "string",
            "description": "Transaction amount (must match payment_amount in request)",
            "example": "0.03"
          }
        },
        "example": {
          "profile_key": "EslVInonBTrSMXZzQapRPPQQwVvjAGgi",
          "security_code": "test123",
          "transaction_amount": "0.03"
        }
      }
    },
    "examples": {
      "CreditCardResponseExample": {
        "summary": "Post Response for a Sales Transaction using a Credit Card",
        "description": "The following example response message is for a credit card sales transaction.",
        "value": {
          "tran_date": "Fri Mar 27 17:42:42 UTC 2020",
          "acct_number": "411111XXXXXX1111",
          "tran_amount": "500.00",
          "tran_type": "Sale",
          "billing_address": "123",
          "tran_id": "e0266d9ceaf234dd99427aebe1a13393",
          "currency_code": "USD",
          "auth_code": "T9939 H",
          "resp_text": "ApprovalT9939H",
          "client_ref_number": "",
          "retrieval_ref_number": "",
          "hpp_tran_id": "1971",
          "billing_zip": "12345",
          "resp_code": "000",
          "exp_date": "1122",
          "invoice_number": ""
        }
      },
      "ACHResponseExample": {
        "summary": "Post Response for a Sales Transaction using ACH",
        "description": "The following response message is for an ACH sales transaction.",
        "value": {
          "auth_type": "WEB",
          "amount": "500.00",
          "account_type": "S",
          "tran_id": "1991",
          "ip_address": "127.0.0.1",
          "ach_request": "SALE",
          "transaction_type": "H",
          "ref_num": "",
          "resp_text": "ACH IP Address Invalid",
          "account_num": "XXXXXX4738",
          "profile_key": "yyyy",
          "profile_id": "xxxx4100006000500000001",
          "transit_num": "XXXXX0399",
          "resp_code": "811",
          "cust_name": "name"
        }
      }
    }
  },
  "tags": [
    {
      "name": "Payment Request",
      "description": "Operations for initiating hosted payment page checkout"
    },
    {
      "name": "Response Handling",
      "description": "HTTP POST responses sent to merchant's configured response_url once a transaction has been approved. \n\nYou can set your Response URL in the Advanced URL Management sections of the Settings and Configuration Page in the Hosted Payments Admin section.\n"
    }
  ],
  "externalDocs": {
    "description": "Contact us",
    "url": "https://merchante.atlassian.net/servicedesk/customer/portal/12/create/101"
  }
}