{ "openapi": "3.0.3", "info": { "title": "Fractal", "version": "1.0.0", "contact": {} }, "servers": [ { "url": "https://testapi.fractalpay.com/api/v1", "description": "Sandbox" }, { "url": "https://api.fractalpay.com/api/v1", "description": "Production" } ], "paths": { "/onboarding": { "post": { "tags": [ "Merchant Onboarding" ], "summary": "Full Merchant Submit", "description": "Full Merchant Submit", "operationId": "fullMerchantSubmit", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "OwnerInfo", "BusinessInfo", "BankingInfo", "ProcessingInfo" ], "properties": { "BankingInfo": { "type": "object", "properties": { "account_number": { "type": "string", "example": "091000019" }, "bank_name": { "type": "string", "example": "Truist" }, "routing_number": { "type": "string", "example": "00212369" } }, "required": [ "account_number", "routing_number", "bank_name" ] }, "BusinessInfo": { "type": "object", "properties": { "business_address": { "type": "string", "example": "333 West Vine Street" }, "business_city": { "type": "string", "example": "Lexington" }, "business_country": { "type": "string", "example": "US" }, "business_email": { "type": "string", "example": "slabreadymixx@mix.com" }, "business_industry": { "type": "string", "example": "7311" }, "business_name": { "type": "string", "example": "Slab Ready Mix" }, "business_phone": { "type": "string", "example": "8599779166" }, "business_state": { "type": "string", "example": "Kentucky" }, "business_zip": { "type": "string", "example": "40517" }, "dba": { "type": "string", "example": "Slab Ready Mix" }, "ein": { "type": "string", "example": "123456789" }, "established_date": { "type": "string", "example": "2024-01-01" }, "ownershiptype": { "type": "string", "example": "LLC" }, "website": { "type": "string", "example": "https://testwebsite.com/" } }, "required": [ "business_address", "business_city", "business_country", "business_email", "business_name", "business_phone", "business_state", "business_zip", "dba", "ein", "website" ] }, "OwnerInfo": { "type": "object", "properties": { "address": { "type": "string", "example": "333 West Vine Street" }, "b_dl_number": { "type": "string", "example": "123123123" }, "b_title": { "type": "string", "example": "Owner" }, "city": { "type": "string", "example": "Lexington" }, "country": { "type": "string", "example": "US" }, "date_of_birth": { "type": "string", "example": "1998-01-17" }, "email": { "type": "string", "example": "slabreadymixx@mix.com" }, "first_name": { "type": "string", "example": "MJ" }, "last_name": { "type": "string", "example": "Mann" }, "ownership_percent": { "type": "string", "example": "100" }, "phone": { "type": "string", "example": "1234567895" }, "ssn": { "type": "string", "example": "555667777" }, "state": { "type": "string", "example": "Kentucky" }, "zip": { "type": "string", "example": "40507" } }, "required": [ "address", "first_name", "last_name", "email", "phone", "date_of_birth", "city", "state", "zip", "country" ] }, "ProcessingInfo": { "type": "object", "properties": { "annualCCSales": { "type": "string", "example": "500000" }, "avgTicket": { "type": "string", "example": "50" }, "legal_b2b": { "type": "string", "example": "50" }, "legal_b2c": { "type": "string", "example": "50" }, "legal_cnpinternet": { "type": "string", "example": "50" }, "legal_cnpphoneemail": { "type": "string", "example": "50" }, "legal_cp": { "type": "string", "example": "50" }, "legal_percentdeliveredover30days": { "type": "string", "example": "50" }, "legal_percentdeliveredsameday": { "type": "string", "example": "50" }, "legal_productssold": { "type": "string", "example": "Goods" }, "percentdelievered7days": { "type": "string", "description": "**Note:** This field must be spelled exactly as listed (`percentdelievered7days`).", "example": "50" }, "percentdelivered14days": { "type": "string", "example": "50" }, "processing_environment": { "type": "string", "example": "Ecommerce" }, "highest_ticket": { "type": "string", "example": "10000", "description": "Highest expected transaction amount." }, "legal_keyed": { "type": "string", "example": "50" } }, "required": [ "processing_environment", "avgTicket", "highest_ticket", "legal_keyed", "annualCCSales", "legal_b2c", "legal_b2b", "legal_cnpinternet", "legal_cnpphoneemail", "legal_percentdeliveredover30days", "legal_percentdeliveredsameday", "percentdelievered7days", "percentdelivered14days", "legal_cp", "legal_productssold" ] } } }, "examples": { "Full Merchant Submit": { "value": { "BankingInfo": { "account_number": "091000019", "bank_name": "Truist", "routing_number": "00212369" }, "BusinessInfo": { "business_address": "333 West Vine Street", "business_city": "Lexington", "business_country": "US", "business_email": "slabreadymixx@mix.com", "business_industry": "7311", "business_name": "Slab Ready Mix", "business_phone": "8599779166", "business_state": "Kentucky", "business_zip": "40517", "dba": "Slab Ready Mix", "ein": "123456789", "established_date": "2024-01-01", "ownershiptype": "LLC", "website": "https://testwebsite.com/" }, "OwnerInfo": { "address": "333 West Vine Street", "b_dl_number": "123123123", "b_title": "Owner", "city": "Lexington", "country": "US", "date_of_birth": "1998-01-17", "email": "slabreadymixx@mix.com", "first_name": "MJ", "last_name": "Mann", "ownership_percent": "100", "phone": "1234567895", "ssn": "555667777", "state": "Kentucky", "zip": "40507" }, "ProcessingInfo": { "annualCCSales": "500000", "avgTicket": "50", "legal_b2b": "50", "legal_b2c": "50", "legal_cnpinternet": "50", "legal_cnpphoneemail": "50", "legal_cp": "50", "legal_percentdeliveredover30days": "50", "legal_percentdeliveredsameday": "50", "legal_productssold": "Goods", "percentdelievered7days": "50", "percentdelivered14days": "50", "processing_environment": "Ecommerce" } } } } } } }, "responses": { "201": { "description": "Full Merchant Submit", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "263" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 15:41:19 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"107-BwzHwJf7KUADnYBdczrA9ih8eLM\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "businessname": { "type": "string", "example": "Slab Ready Mix" }, "email": { "type": "string", "example": "slabreadymixx@mix.com" }, "merchant_key": { "type": "string", "example": "9f496121110e19b36b862e97559bbd9ffe0bd0a7335b2884e071ea6d6d59cc34" }, "public_key": { "type": "string", "example": "28e2464f8b8726847cec7196beb7d0c6" } } }, "message": { "type": "string", "example": "Merchant onboarding successfully" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Full Merchant Submit": { "value": { "data": { "businessname": "Slab Ready Mix", "email": "slabreadymixx@mix.com", "merchant_key": "9f496121110e19b36b862e97559bbd9ffe0bd0a7335b2884e071ea6d6d59cc34", "public_key": "28e2464f8b8726847cec7196beb7d0c6" }, "message": "Merchant onboarding successfully", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchant": { "get": { "tags": [ "Merchant Onboarding" ], "summary": "Get Merchants by Client", "description": "Get Merchants by Client", "operationId": "getMerchantsByClient", "responses": { "200": { "description": "Get Merchants by Client", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "1046" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 15:44:55 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"416-Fz+tgXSSm3x1P62JF6UvwhGAO2g\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "businessname": { "type": "string", "example": "Rogue 6 Ready Mix" }, "email": { "type": "string", "example": "jpdemo@fractal.com" }, "first_name": { "type": "string", "example": "JP" }, "join_date": { "type": "string", "example": "2024-06-05T13:44:25.000Z" }, "last_name": { "type": "string", "example": "Gound" }, "merchant_id": { "type": "string", "example": "m_b9518c1f23" }, "phonenumber": { "type": "string", "example": "1234567895" }, "public_data": { "type": "object", "properties": { "public_key": { "type": "string", "example": "b03d94339a5a899509e3b05266a1f601" } } }, "website": { "type": "string", "example": "https://testwebsite.com/" } } }, "example": [ { "businessname": "Rogue 6 Ready Mix", "email": "jpdemo@fractal.com", "first_name": "JP", "join_date": "2024-06-05T13:44:25.000Z", "last_name": "Gound", "merchant_id": "m_b9518c1f23", "phonenumber": "1234567895", "public_data": { "public_key": "b03d94339a5a899509e3b05266a1f601" }, "website": "https://testwebsite.com/" }, { "businessname": "Celtic Ready Mix", "email": "droooobie@fractall.com", "first_name": "Drew", "join_date": "2024-07-22T19:18:36.000Z", "last_name": "Rice", "merchant_id": "m_31c5d8c748", "phonenumber": "1234567895", "public_data": { "public_key": "38dbd500cb2b0d1c9f4eaac18c0ad131" }, "website": "https://testwebsite.com/" }, { "businessname": "Slab Ready Mix", "email": "slabreadymix@fractall.com", "first_name": "MJ", "join_date": "2024-08-20T18:44:35.000Z", "last_name": "Mann", "merchant_id": "m_3f5fa50c5f", "phonenumber": "1234567895", "public_data": { "public_key": "17fd596bb19ad222eaf0207582ce62da" }, "website": "https://testwebsite.com/" } ] }, "message": { "type": "string", "example": "Merchants fetched successfully" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Get Merchants by Client": { "value": { "data": [ { "businessname": "Rogue 6 Ready Mix", "email": "jpdemo@fractal.com", "first_name": "JP", "join_date": "2024-06-05T13:44:25.000Z", "last_name": "Gound", "merchant_id": "m_b9518c1f23", "phonenumber": "1234567895", "public_data": { "public_key": "b03d94339a5a899509e3b05266a1f601" }, "website": "https://testwebsite.com/" }, { "businessname": "Celtic Ready Mix", "email": "droooobie@fractall.com", "first_name": "Drew", "join_date": "2024-07-22T19:18:36.000Z", "last_name": "Rice", "merchant_id": "m_31c5d8c748", "phonenumber": "1234567895", "public_data": { "public_key": "38dbd500cb2b0d1c9f4eaac18c0ad131" }, "website": "https://testwebsite.com/" }, { "businessname": "Slab Ready Mix", "email": "slabreadymix@fractall.com", "first_name": "MJ", "join_date": "2024-08-20T18:44:35.000Z", "last_name": "Mann", "merchant_id": "m_3f5fa50c5f", "phonenumber": "1234567895", "public_data": { "public_key": "17fd596bb19ad222eaf0207582ce62da" }, "website": "https://testwebsite.com/" } ], "message": "Merchants fetched successfully", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/requests": { "post": { "tags": [ "Payment Collection Methods", "Requests" ], "summary": "Payment Request", "description": "Sends a payment request to a customer via SMS and/or email. Returns a pay link the customer uses to complete payment. Set preauth: true to issue a preauthorization instead of a charge \u2014 the customer authorizes the amount without being charged immediately. Fires a payment.success webhook on completed payment, or a preauth webhook on successful preauthorization.", "operationId": "paymentRequest", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id", "amount", "merchant_key" ], "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique API key.", "example": "{{merchant_key}}" }, "amount": { "type": "string", "description": "Payment amount.", "example": "10.00" }, "order_id": { "type": "string", "description": "Your unique order reference. Max 100 characters.", "example": "5467" }, "phone_number": { "type": "string", "description": "Customer phone number. If provided, an SMS with the pay link is sent.", "example": "7777771234" }, "email": { "type": "string", "description": "Customer email address. If provided, an email with the pay link is sent.", "example": "customer@example.com" }, "name": { "type": "string", "description": "Customer name. Used in the email template.", "example": "Jane Smith" }, "preauth": { "type": "boolean", "description": "Set to true to issue a preauthorization. The customer authorizes the amount without being charged immediately.", "example": true }, "pass_fee": { "type": "boolean", "description": "Pass the processing fee to the customer.", "example": true }, "require_3ds": { "type": "boolean", "description": "Require 3D Secure authentication.", "example": false }, "allow_card": { "type": "boolean", "description": "Allow card as a payment method. At least one of allow_card or allow_ach must be true.", "default": true, "example": true }, "allow_ach": { "type": "boolean", "description": "Allow ACH as a payment method. At least one of allow_card or allow_ach must be true.", "default": true, "example": true }, "invoice_number": { "type": "string", "description": "Invoice reference. Alphanumeric, max 100 characters.", "example": "345" }, "sub_merchant_key": { "type": "string", "description": "Sub-merchant key, if applicable.", "example": "" }, "discount": { "type": "string", "description": "Discount amount.", "example": "0.00" }, "surcharge": { "type": "string", "description": "Surcharge amount.", "example": "0.00" }, "tax": { "type": "string", "description": "Tax amount.", "example": "0.00" }, "description": { "type": "string", "description": "Payment description." } } }, "examples": { "Standard Payment Request": { "value": { "merchant_key": "{{merchant_key}}", "amount": "10.00", "order_id": "5467", "phone_number": "7777771234", "email": "customer@example.com", "allow_card": true, "allow_ach": true } }, "Preauth Payment Request": { "value": { "merchant_key": "{{merchant_key}}", "amount": "10.00", "order_id": "5467", "phone_number": "7777771234", "email": "customer@example.com", "preauth": true, "pass_fee": true, "require_3ds": false, "invoice_number": "345", "allow_card": true, "allow_ach": true } } } } } }, "responses": { "200": { "description": "Payment request created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order_id you provided.", "example": "5467" }, "link_id": { "type": "string", "description": "Short code identifying the pay link.", "example": "gsgqll4xfa7" }, "pay_link": { "type": "string", "description": "Full URL to send to the customer to complete payment or preauthorization.", "example": "https://testapi.fractalpay.com/authcheck-paymentlink/gsgqll4xfa7" } } } } }, "examples": { "Preauth Request": { "value": { "message": "Authorization request has been sent", "data": { "order_id": "5467", "link_id": "gsgqll4xfa7", "pay_link": "https://testapi.fractalpay.com/authcheck-paymentlink/gsgqll4xfa7" } } }, "Standard Payment Request": { "value": { "message": "Text request has been sent", "data": { "order_id": "5467", "link_id": "gsgqll4xfa7", "pay_link": "https://testapi.fractalpay.com/authcheck-paymentlink/gsgqll4xfa7" } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/requests/{customerId}": { "post": { "tags": [ "Payment Collection Methods", "Requests" ], "summary": "Payment Request Customer", "description": "Payment Request Customer", "operationId": "paymentRequestCustomer", "parameters": [ { "name": "api_key", "in": "header", "schema": { "type": "string", "example": "8af9a5a0e6338fbafd8d2fa7a688fd16363cc865c6e6ede3002d041c2613cb99" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "4.00" }, "isRequestCard": { "type": "boolean", "example": true }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "order_id": { "type": "string", "example": "512345" }, "preauth": { "type": "boolean", "example": false }, "invoice_number": { "type": "string", "example": "345" }, "allow_card": { "type": "boolean", "default": true, "example": true, "description": "Allow card as a payment method. At least one of `allow_card` or `allow_ach` must be `true` \u2014 setting both to `false` will result in an error." }, "allow_ach": { "type": "boolean", "default": true, "example": true, "description": "Allow ACH as a payment method. At least one of `allow_card` or `allow_ach` must be `true` \u2014 setting both to `false` will result in an error." } }, "required": [ "order_id", "amount", "merchant_key" ] }, "examples": { "Authorization Request Customer": { "value": { "amount": "4.00", "merchant_key": "{{merchant_key}}", "order_id": "54514", "preauth": true } }, "Payment Request Customer": { "value": { "amount": "4.00", "merchant_key": "{{merchant_key}}", "order_id": "512345", "preauth": false, "invoice_number": "345" } }, "Request Card With Customer": { "value": { "isRequestCard": true, "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Authorization Request Customer / Request Card With Customer", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "58" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:09:29 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"3a-WOay6XweLLnkuAfHML9DiSmFzMc\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "example": "54514" }, "pay_link": { "type": "string", "example": "http://localhost:8082/pre-auth/bb40a9028ef7e65521bb4d21ee491437?amount=4.00&order_id=54514" }, "sales_id": { "type": "string", "example": "" } } }, "message": { "type": "string", "example": "Text request has been sent" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Authorization Request Customer": { "value": { "data": { "order_id": "54514", "pay_link": "http://localhost:8082/pre-auth/bb40a9028ef7e65521bb4d21ee491437?amount=4.00&order_id=54514", "sales_id": "" }, "message": "Text request has been sent" } }, "Request Card With Customer": { "value": { "message": "Card request sent successfully", "result": true } } } } } }, "201": { "description": "Payment Request Customer", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "192" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:04:34 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"c0-b2gGN11PBu5rPGm79OjalhWeZq4\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "example": "512345" }, "qr_code_link": { "type": "string", "example": "https://testapi.fractalpay.com/authcheck-paymentlink/842gd6vkh8g" }, "sales_id": { "type": "string", "example": "txn_c9d4899edb" } } }, "message": { "type": "string", "example": "Text request has been sent" } } }, "examples": { "Payment Request Customer": { "value": { "data": { "order_id": "512345", "qr_code_link": "https://testapi.fractalpay.com/authcheck-paymentlink/842gd6vkh8g", "sales_id": "txn_c9d4899edb" }, "message": "Text request has been sent" } } } } } } }, "security": [ { "basicAuth": [] } ] }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "The customer's unique ID. Returned in the `customer_id` field of the Create Customer (`POST /customers/add`) response. To retrieve a list of all customers and their IDs, use the Get Customers (`GET /customers`) endpoint.", "schema": { "type": "string" } } ] }, "/pay-link": { "post": { "tags": [ "Payment Collection Methods" ], "summary": "Create Payment Link", "description": "Create Payment Link", "operationId": "createPaymentLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "4.55" }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "order_id": { "type": "string", "example": "22111fdz" }, "invoice_number": { "type": "string", "example": "345" }, "allow_card": { "type": "boolean", "default": true, "example": true, "description": "Allow card as a payment method. At least one of `allow_card` or `allow_ach` must be `true` \u2014 setting both to `false` will result in an error." }, "allow_ach": { "type": "boolean", "default": true, "example": true, "description": "Allow ACH as a payment method. At least one of `allow_card` or `allow_ach` must be `true` \u2014 setting both to `false` will result in an error." } }, "required": [ "order_id", "amount", "merchant_key" ] }, "examples": { "Create Payment Link": { "value": { "amount": "4.55", "merchant_key": "{{merchant_key}}", "order_id": "22111fdz", "invoice_number": "345" } } } } } }, "responses": { "201": { "description": "Create Link", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "219" } }, "Date": { "schema": { "type": "string", "example": "Thu, 08 Aug 2024 18:41:02 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"db-bXu3eOWR5CrQu8qUg+QpyajKPrA\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "example": "22111fdz" }, "payment_link": { "type": "string", "example": "https://testapi.fractalpay.com/authcheck-paymentlink/u6j3garacoj" }, "sales_id": { "type": "string", "example": "txn_c2e0adab55" } } }, "message": { "type": "string", "example": "Quick Pay Order created successfully." }, "result": { "type": "boolean", "example": true } } }, "examples": { "Create Link": { "value": { "data": { "order_id": "22111fdz", "payment_link": "https://testapi.fractalpay.com/authcheck-paymentlink/u6j3garacoj", "sales_id": "txn_c2e0adab55" }, "message": "Quick Pay Order created successfully.", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/order/api-qr_code_link": { "post": { "tags": [ "Payment Collection Methods" ], "summary": "QR Payment Link", "description": "QR Payment Link", "operationId": "qrPaymentLink", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "2.00" }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "order_id": { "type": "string", "example": "24400" } }, "required": [ "amount", "merchant_key", "order_id" ] }, "examples": { "QR Payment Link": { "value": { "amount": "2.00", "merchant_key": "{{merchant_key}}", "order_id": "24400" } } } } } }, "responses": { "201": { "description": "QR Payment Link", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "193" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:12:16 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"c1-qzovrDgjA6MzpTR5iSpF4ZAJxMs\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "example": "24400" }, "qr_code_link": { "type": "string", "example": "https://testapi.fractalpay.com/authcheck-paymentlink/pqy8mwj4tjl" }, "sales_id": { "type": "string", "example": "txn_c9d48e46ed" } } }, "message": { "type": "string", "example": "QR code URL has been created" } } }, "examples": { "QR Payment Link": { "value": { "data": { "order_id": "24400", "qr_code_link": "https://testapi.fractalpay.com/authcheck-paymentlink/pqy8mwj4tjl", "sales_id": "txn_c9d48e46ed" }, "message": "QR code URL has been created" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/pay-link/{linkId}": { "delete": { "tags": [ "Payment Collection Methods" ], "summary": "Delete Pay Link", "description": "Delete Pay Link", "operationId": "deletePayLink", "parameters": [ { "name": "linkId", "in": "path", "required": true, "description": "The `link_id` of the pay link to delete.", "schema": { "type": "string", "example": "ord_a64b33f04e" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" } }, "required": [ "merchant_key" ] }, "examples": { "Delete Pay Link": { "value": { "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Delete Pay Link", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "link_id": { "type": "string", "example": "ord_a64b33f04e" }, "message": { "type": "string", "example": "link deleted" } } }, "examples": { "Delete Pay Link": { "value": { "result": true, "link_id": "ord_a64b33f04e", "message": "link deleted" } } } } } }, "404": { "description": "Link not found, does not belong to the merchant, or has already been paid", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Link not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchant/remote_deposit_capture": { "post": { "tags": [ "Payment Collection Methods" ], "summary": "Remote Deposit Capture", "description": "Submit a check image for remote deposit capture. Sends the front and back images of a check as a multipart/form-data upload.\n\n**Note:** The merchant must have Skyfi ACH credentials configured \u2014 requests will fail with `\"Skyfi merchant or account detail not found\"` if credentials are not set up.", "operationId": "remoteDepositCapture", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount of the check.", "example": 100.0 }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "device": { "type": "string", "description": "Device OS name.", "example": "iOS" }, "front_file": { "type": "string", "format": "binary", "description": "Image of the front of the check." }, "back_file": { "type": "string", "format": "binary", "description": "Image of the back of the check." } }, "required": [ "amount", "merchant_key", "device", "front_file", "back_file" ] } } } }, "responses": { "200": { "description": "Remote Deposit Capture", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Remote deposit capture initiated successfully." }, "data": { "type": "object", "properties": { "transactionId": { "type": "string", "example": "txn_abc123" }, "amount": { "type": "string", "example": "100.00" } } } } }, "examples": { "Remote Deposit Capture": { "value": { "result": true, "message": "Remote deposit capture initiated successfully.", "data": { "transactionId": "txn_abc123", "amount": "100.00" } } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/preauth/update": { "post": { "tags": [ "Preauthorizations" ], "summary": "Update Pre-Authorization", "description": "Increases or decreases the authorized amount on an existing preauthorization. If new_authorized_amount is greater than last_authorized_amount, an incremental authorization is issued and a preauth.increment webhook fires. If new_authorized_amount is less, a partial reversal is issued and a preauth.decrement webhook fires. last_authorized_amount must match the current authorized amount on the record.", "operationId": "updatePreAuthorization", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id", "merchant_key", "last_authorized_amount", "new_authorized_amount" ], "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique API key.", "example": "{{merchant_key}}" }, "transaction_id": { "type": "string", "description": "The guid of the existing preauthorization to update. Always use the original preauthorization transaction ID — not the ID returned by a previous update.", "example": "txn_77c9a625a3" }, "last_authorized_amount": { "type": "string", "description": "The current authorized amount. Must match the amount on record or the request returns an Amount mismatch error.", "example": "10.00" }, "new_authorized_amount": { "type": "string", "description": "The target authorized amount. Greater than last_authorized_amount triggers an increment; less triggers a decrement.", "example": "11.00" }, "order_id": { "type": "string", "description": "Your order reference.", "example": "5467" } } }, "examples": { "Increment (raise authorization)": { "value": { "merchant_key": "{{merchant_key}}", "transaction_id": "txn_77c9a625a3", "last_authorized_amount": "10.00", "new_authorized_amount": "11.00", "order_id": "5467" } }, "Decrement (partial reversal)": { "value": { "merchant_key": "{{merchant_key}}", "transaction_id": "txn_77c9a625a3", "last_authorized_amount": "10.00", "new_authorized_amount": "8.00", "order_id": "5467" } } } } } }, "responses": { "200": { "description": "Authorization updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Amount Updated Successfully" }, "data": { "type": "object", "properties": { "Status": { "type": "string", "description": "Gateway approval status.", "example": "Approved" }, "Account": { "type": "string", "description": "Last four digits of the card.", "example": "0043" }, "Brand": { "type": "string", "description": "Card brand.", "example": "Visa" }, "AuthCode": { "type": "string", "description": "Authorization code from the gateway.", "example": "" }, "Authorized": { "type": "string", "description": "New authorized amount after the update.", "example": "11.00" }, "transaction_id": { "type": "string", "description": "The preauth transaction ID.", "example": "txn_77c9a625a3" }, "orderid": { "type": "string", "description": "The associated order ID.", "example": "5467" } } } } }, "examples": { "Increment response": { "value": { "result": true, "message": "Amount Updated Successfully", "data": { "Status": "Approved", "Account": "0043", "Brand": "Visa", "AuthCode": "", "Authorized": "11.00", "transaction_id": "txn_77c9a625a3", "orderid": "5467" } } } } } } }, "400": { "description": "Update failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string" } } }, "examples": { "Amount mismatch": { "value": { "result": false, "message": "Amount mismatch" } }, "Cannot increase already-decremented auth": { "value": { "result": false, "message": "Authorization can only be decreased, captured, or voided." } }, "Cannot decrease already-incremented auth": { "value": { "result": false, "message": "Authorization can only be increased, captured, or voided." } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/preauth/capture": { "post": { "tags": [ "Preauthorizations" ], "summary": "Capture Pre-Authorization", "description": "Charges the customer for the currently authorized amount on an existing preauthorization. Converts the preauth into a completed transaction. Fires a preauth.charge webhook on success.", "operationId": "capturePreAuthorization", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "merchant_key", "transaction_id" ], "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique API key.", "example": "{{merchant_key}}" }, "transaction_id": { "type": "string", "description": "The guid of the preauthorization to capture. Always use the original preauthorization transaction ID — not the ID returned by a previous update.", "example": "txn_f84144f73a" } } }, "examples": { "Capture Pre-Authorization": { "value": { "merchant_key": "{{merchant_key}}", "transaction_id": "txn_f84144f73a" } } } } } }, "responses": { "200": { "description": "Capture successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Payment captured successfully." }, "data": { "type": "object", "properties": { "Status": { "type": "string", "description": "Gateway approval status.", "example": "Approved" }, "Account": { "type": "string", "description": "Last four digits of the card.", "example": "0043" }, "Brand": { "type": "string", "description": "Card brand.", "example": "Visa" }, "AuthCode": { "type": "string", "description": "Authorization code from the gateway.", "example": "" }, "amount": { "type": "string", "description": "Captured amount.", "example": "11.00" }, "Authorized": { "type": "number", "description": "Authorized amount.", "example": 11 }, "orderid": { "type": "string", "description": "The associated order ID.", "example": "5467" }, "transaction_id": { "type": "string", "description": "The resulting completed transaction ID.", "example": "txn_77c9a625a3" }, "net_amount": { "type": "number", "description": "Amount after fees.", "example": 10.64 } } } } }, "examples": { "Capture Pre-Authorization": { "value": { "result": true, "message": "Payment captured successfully.", "data": { "Status": "Approved", "Account": "0043", "Brand": "Visa", "AuthCode": "", "amount": "11.00", "Authorized": 11, "orderid": "5467", "transaction_id": "txn_77c9a625a3", "net_amount": 10.64 } } } } } } }, "400": { "description": "Capture failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string" } } }, "examples": { "Not found": { "value": { "result": false, "message": "Authorization not found" } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/customers/charge/{customerId}": { "post": { "tags": [ "Customers", "Charging Customer" ], "summary": "Charge Customer", "description": "Charge Customer", "operationId": "chargeCustomer", "parameters": [ { "name": "", "in": "query", "schema": { "type": "string", "example": "" } }, { "name": "", "in": "header", "schema": { "type": "string", "example": "9ee4a08a-2e34-11ef-af4e-0ef0812e6179" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "example": 1 }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "order_id": { "type": "string", "example": "5465446" }, "preAuth": { "type": "boolean", "example": true } }, "required": [ "amount", "merchant_key", "order_id", "preAuth" ] }, "examples": { "Charge Customer": { "value": { "amount": 1, "merchant_key": "{{merchant_key}}", "order_id": "556465" } }, "Charge Customer PreAuth": { "value": { "amount": 1, "merchant_key": "{{merchant_key}}", "order_id": "5465446", "preAuth": true } } } }, "text/plain": { "examples": { "Charge Customer": { "value": "{\n \"amount\": 1.00,\n // \"preAuth\": true,\n \"merchant_key\":\"{{merchant_key}}\"\n}" } } } } }, "responses": { "200": { "description": "Charge Customer / Charge Customer PreAuth", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "115" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:39:46 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"73-pMHpxmBvE9Ipxs6pPFn/qUbFiS4\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "txn_68e93a56fa" } } }, "message": { "type": "string", "example": "Payment captured successfully." }, "result": { "type": "boolean", "example": true }, "transaction_id": { "type": "string", "example": "txn_0e99eb7c5a" } } }, "examples": { "Charge Customer": { "value": { "message": "Payment captured successfully.", "result": true, "transaction_id": "txn_0e99eb7c5a" } }, "Charge Customer PreAuth": { "value": { "data": { "transaction_id": "txn_68e93a56fa" }, "message": "Authorization Approved", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "The customer's unique ID. Returned in the `customer_id` field of the Create Customer (`POST /customers/add`) response. To retrieve a list of all customers and their IDs, use the Get Customers (`GET /customers`) endpoint.", "schema": { "type": "string" } } ] }, "/customers/add": { "post": { "tags": [ "Customers" ], "summary": "Create Customer", "description": "Create Customer", "operationId": "createCustomer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "john@fractal.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "phone_number": { "type": "string", "example": "5134140000" } }, "required": [ "first_name", "merchant_key" ] }, "examples": { "Create Customer": { "value": { "email": "john@fractal.com", "first_name": "John", "last_name": "Doe", "merchant_key": "{{merchant_key}}", "phone_number": "5134140000" } } } } } }, "responses": { "200": { "description": "Create Customer", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "183" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:33:56 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"b7-jMine09A3WpfIP3532nHVRSc52o\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer_email": { "type": "string", "example": "john@fractal.com" }, "customer_id": { "type": "string", "example": "c_f10702845f" }, "customer_phone": { "type": "string", "example": "5134140000" } } }, "message": { "type": "string", "example": "Customer added successfully" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Create Customer": { "value": { "data": { "customer_email": "john@fractal.com", "customer_id": "c_f10702845f", "customer_phone": "5134140000" }, "message": "Customer added successfully", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/customers/{customerId}": { "get": { "tags": [ "Customers" ], "summary": "Get Customer", "description": "Get Customer", "operationId": "getCustomer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" } } }, "examples": { "Get Customer": { "value": { "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Get Customer", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "175" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:34:08 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"af-c9r+5eQgZmeDihdqyHqF7SxYGE4\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "customer_email": { "type": "string", "example": "johndoe@fractalpay.com" }, "customer_id": { "type": "string", "example": "c_0c5f67e242" }, "customer_phone": { "type": "string", "example": "8554147444" } } }, "message": { "type": "string", "example": "Customer details" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Get Customer": { "value": { "data": { "customer_email": "johndoe@fractalpay.com", "customer_id": "c_0c5f67e242", "customer_phone": "8554147444" }, "message": "Customer details", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "The customer's unique ID. Returned in the `customer_id` field of the Create Customer (`POST /customers/add`) response. To retrieve a list of all customers and their IDs, use the Get Customers (`GET /customers`) endpoint.", "schema": { "type": "string" } } ] }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "Get Customers", "description": "Get Customers", "operationId": "getCustomers", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" } }, "required": [ "merchant_key" ] }, "examples": { "Get Customers": { "value": { "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Get Customers", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "493" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:37:03 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"1ed-LAW37h1suBd3u3hQJT62UPI6KIo\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "allList": { "type": "array", "items": { "type": "object", "properties": { "Email": { "type": "string", "example": "john@fractal.com" }, "Phone": { "type": "string", "example": "5134140000" }, "create_date": { "type": "string", "example": "2024-08-21T16:32:22.000Z" }, "customer_id": { "type": "string", "example": "c_f10702845f" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Woe" } } }, "example": [ { "Email": "john@fractal.com", "Phone": "5134140000", "create_date": "2024-08-21T16:32:22.000Z", "customer_id": "c_f10702845f", "first_name": "John", "last_name": "Woe" }, { "Email": "mike@james.com", "Phone": "4548591474", "create_date": "2024-07-15T16:12:35.000Z", "customer_id": "c_0c5f67e242", "first_name": "John F", "last_name": "Doe" } ] }, "page": { "type": "number", "example": 1 }, "perPage": { "type": "number", "example": 20 }, "totalCount": { "type": "number", "example": 2 }, "totalPage": { "type": "number", "example": 1 } } }, "message": { "type": "string", "example": "All customer list" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Get Customers": { "value": { "data": { "allList": [ { "Email": "john@fractal.com", "Phone": "5134140000", "create_date": "2024-08-21T16:32:22.000Z", "customer_id": "c_f10702845f", "first_name": "John", "last_name": "Woe" }, { "Email": "mike@james.com", "Phone": "4548591474", "create_date": "2024-07-15T16:12:35.000Z", "customer_id": "c_0c5f67e242", "first_name": "John F", "last_name": "Doe" } ], "page": 1, "perPage": 20, "totalCount": 2, "totalPage": 1 }, "message": "All customer list", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/customers/request-card/{customerId}": { "post": { "tags": [ "Customers" ], "summary": "Request Card", "description": "Request Card", "operationId": "requestCard", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" } } }, "examples": { "Request Card": { "value": { "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Request Card", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "53" } }, "Date": { "schema": { "type": "string", "example": "Wed, 12 Jun 2024 16:56:04 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"35-7LYg40hm0FW0EfyITCKmrLFxc14\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Request sent successfully" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Request Card": { "value": { "message": "Request sent successfully", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] }, "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "The customer's unique ID. Returned in the `customer_id` field of the Create Customer (`POST /customers/add`) response. To retrieve a list of all customers and their IDs, use the Get Customers (`GET /customers`) endpoint.", "schema": { "type": "string" } } ] }, "/merchant/transactions": { "get": { "tags": [ "Transactions" ], "summary": "Get Transactions", "description": "Get Transactions", "operationId": "getTransactions", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string", "example": "2024-01-15" }, "limit": { "type": "string", "example": "20" }, "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "pageNumber": { "type": "number", "example": 0 }, "to_date": { "type": "string", "example": "2024-07-18" } }, "required": [ "merchant_key" ] }, "examples": { "Get Transactions": { "value": { "from_date": "2024-01-15", "limit": "20", "merchant_key": "{{merchant_key}}", "pageNumber": 0, "to_date": "2024-07-18" } } } } } }, "responses": { "200": { "description": "Get Transactions", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "4451" } }, "Date": { "schema": { "type": "string", "example": "Wed, 21 Aug 2024 16:52:54 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"1163-ksnM6JvIou+q4vl2UFTU1o0veuE\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "example": "1.00" }, "created_date": { "type": "string", "example": "2024-07-15T22:47:06.000Z" }, "fee_percentage": { "type": "string", "example": "0.0000000" }, "net_amount": { "type": "number", "example": 0.97 }, "other_details": { "type": "object", "properties": { "auth_code": { "type": "string", "example": "y1sskla5N" }, "card_brand": { "type": "string", "example": "VISA" }, "last_four": { "type": "string", "example": "0043" } } }, "transaction_id": { "type": "string", "example": "txn_294ac4cb42" } } }, "example": [ { "amount": "1.00", "created_date": "2024-07-15T22:47:06.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "y1sskla5N", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_294ac4cb42" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:44.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "9nYTCO3", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_f83920db42" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:27.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "ZZ072OJeLk", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_ee8a4828" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:14.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "IEWrahzKAB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e6bbd59542" }, { "amount": "1.00", "created_date": "2024-07-15T22:43:48.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "jPXI7gxQ", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_b330e46b42" }, { "amount": "1.00", "created_date": "2024-07-15T16:32:20.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "ZvaoUl4Lyq", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_cec8b3b142" }, { "amount": "1.00", "created_date": "2024-07-15T16:29:25.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "i6a7il0", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_664f064a42" }, { "amount": "1.00", "created_date": "2024-07-15T16:19:33.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "0N1BuUwq", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_057629e642" }, { "amount": "1.00", "created_date": "2024-07-15T16:18:46.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "k7NiHFSOQF", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e95bd20742" }, { "amount": "4.55", "created_date": "2024-07-11T16:13:29.000Z", "fee_percentage": "0.1365000", "net_amount": 4.41, "other_details": { "auth_code": "8eD7NXQ0", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_82b654dc3f" }, { "amount": "8.00", "created_date": "2024-07-09T17:59:34.000Z", "fee_percentage": "0.2400000", "net_amount": 7.76, "other_details": { "auth_code": "M2bxfXS", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_ffd2c8343e" }, { "amount": "3.00", "created_date": "2024-07-09T15:57:10.000Z", "fee_percentage": "0.0900000", "net_amount": 2.91, "other_details": { "auth_code": "WxxkG24J", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e656c18b3e" }, { "amount": "4.00", "created_date": "2024-07-09T15:54:40.000Z", "fee_percentage": "0.0000000", "net_amount": 4, "other_details": { "auth_code": "7caxq68qT", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_8d1d35a93e" }, { "amount": "7.00", "created_date": "2024-07-09T15:28:51.000Z", "fee_percentage": "0.0000000", "net_amount": 7, "other_details": { "auth_code": "zGlAoC3Zk", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_f1e946cc3e" }, { "amount": "6.00", "created_date": "2024-07-08T17:13:52.000Z", "fee_percentage": "0.0000000", "net_amount": 2.82, "other_details": { "auth_code": "cTbiOd2dwY", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_72ea4c0e3d" }, { "amount": "2.00", "created_date": "2024-07-08T17:09:17.000Z", "fee_percentage": "0.0000000", "net_amount": -1.06, "other_details": { "auth_code": "C1AQg5S", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_cf54dd133d" }, { "amount": "3.00", "created_date": "2024-07-08T16:12:32.000Z", "fee_percentage": "0.0000000", "net_amount": 2.91, "other_details": { "auth_code": "00tCCRUMEB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e1d611ae3d" }, { "amount": "8.00", "created_date": "2024-07-08T16:07:16.000Z", "fee_percentage": "0.0000000", "net_amount": 7.76, "other_details": { "auth_code": "M5a0IKoB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_2582623a3d" } ] }, "message": { "type": "string", "example": "Merchant's Transactions" }, "result": { "type": "boolean", "example": true }, "total": { "type": "number", "example": 18 } } }, "examples": { "Get Transactions": { "value": { "data": [ { "amount": "1.00", "created_date": "2024-07-15T22:47:06.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "y1sskla5N", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_294ac4cb42" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:44.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "9nYTCO3", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_f83920db42" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:27.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "ZZ072OJeLk", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_ee8a4828" }, { "amount": "1.00", "created_date": "2024-07-15T22:45:14.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "IEWrahzKAB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e6bbd59542" }, { "amount": "1.00", "created_date": "2024-07-15T22:43:48.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "jPXI7gxQ", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_b330e46b42" }, { "amount": "1.00", "created_date": "2024-07-15T16:32:20.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "ZvaoUl4Lyq", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_cec8b3b142" }, { "amount": "1.00", "created_date": "2024-07-15T16:29:25.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "i6a7il0", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_664f064a42" }, { "amount": "1.00", "created_date": "2024-07-15T16:19:33.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "0N1BuUwq", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_057629e642" }, { "amount": "1.00", "created_date": "2024-07-15T16:18:46.000Z", "fee_percentage": "0.0000000", "net_amount": 0.97, "other_details": { "auth_code": "k7NiHFSOQF", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e95bd20742" }, { "amount": "4.55", "created_date": "2024-07-11T16:13:29.000Z", "fee_percentage": "0.1365000", "net_amount": 4.41, "other_details": { "auth_code": "8eD7NXQ0", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_82b654dc3f" }, { "amount": "8.00", "created_date": "2024-07-09T17:59:34.000Z", "fee_percentage": "0.2400000", "net_amount": 7.76, "other_details": { "auth_code": "M2bxfXS", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_ffd2c8343e" }, { "amount": "3.00", "created_date": "2024-07-09T15:57:10.000Z", "fee_percentage": "0.0900000", "net_amount": 2.91, "other_details": { "auth_code": "WxxkG24J", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e656c18b3e" }, { "amount": "4.00", "created_date": "2024-07-09T15:54:40.000Z", "fee_percentage": "0.0000000", "net_amount": 4, "other_details": { "auth_code": "7caxq68qT", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_8d1d35a93e" }, { "amount": "7.00", "created_date": "2024-07-09T15:28:51.000Z", "fee_percentage": "0.0000000", "net_amount": 7, "other_details": { "auth_code": "zGlAoC3Zk", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_f1e946cc3e" }, { "amount": "6.00", "created_date": "2024-07-08T17:13:52.000Z", "fee_percentage": "0.0000000", "net_amount": 2.82, "other_details": { "auth_code": "cTbiOd2dwY", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_72ea4c0e3d" }, { "amount": "2.00", "created_date": "2024-07-08T17:09:17.000Z", "fee_percentage": "0.0000000", "net_amount": -1.06, "other_details": { "auth_code": "C1AQg5S", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_cf54dd133d" }, { "amount": "3.00", "created_date": "2024-07-08T16:12:32.000Z", "fee_percentage": "0.0000000", "net_amount": 2.91, "other_details": { "auth_code": "00tCCRUMEB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_e1d611ae3d" }, { "amount": "8.00", "created_date": "2024-07-08T16:07:16.000Z", "fee_percentage": "0.0000000", "net_amount": 7.76, "other_details": { "auth_code": "M5a0IKoB", "card_brand": "VISA", "last_four": "0043" }, "transaction_id": "txn_2582623a3d" } ], "message": "Merchant's Transactions", "result": true, "total": 18 } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/merchant/transactions/{transaction_id}": { "get": { "tags": [ "Transactions" ], "summary": "Get Transaction", "description": "Get Transaction", "operationId": "getTransaction", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Unique transaction ID. Returned in the `transaction_id` field of the Get Transactions (`GET /merchant/transactions`) response.", "schema": { "type": "string", "example": "txn_294ac4cb42" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" } }, "required": [ "merchant_key" ] }, "examples": { "Get Transaction": { "value": { "merchant_key": "{{merchant_key}}" } } } } } }, "responses": { "200": { "description": "Get Transaction", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "example": "*" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } }, "Content-Length": { "schema": { "type": "string", "example": "528" } }, "Date": { "schema": { "type": "string", "example": "Wed, 19 Jun 2024 16:26:35 GMT" } }, "ETag": { "schema": { "type": "string", "example": "W/\"210-6cXgOCFCrI+pnwZogOHsrlzM93k\"" } }, "Keep-Alive": { "schema": { "type": "string", "example": "timeout=5" } }, "X-Powered-By": { "schema": { "type": "string", "example": "Express" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "example": "3000.00" }, "fee_percentage": { "type": "string", "example": "0.0000000" }, "net_amount": { "type": "number", "example": 2920 }, "other_details": { "type": "object", "properties": { "authcode": { "type": "string", "example": "VDhdH5BWz" }, "cardType": { "type": "string", "example": "M/C" }, "lastFourDigits": { "type": "string", "example": "0060" } } }, "transaction_date": { "type": "string", "example": "2024-04-15T12:01:48.000Z" }, "transaction_id": { "type": "string", "example": "txn_f0478a5ffb" } } }, "example": [ { "amount": "3000.00", "fee_percentage": "0.0000000", "net_amount": 2920, "other_details": { "authcode": "VDhdH5BWz", "cardType": "M/C", "lastFourDigits": "0060" }, "transaction_date": "2024-04-15T12:01:48.000Z", "transaction_id": "txn_f0478a5ffb" } ] }, "message": { "type": "string", "example": "Transaction fetched successfully" }, "result": { "type": "boolean", "example": true } } }, "examples": { "Get Transaction": { "value": { "data": [ { "amount": "3000.00", "fee_percentage": "0.0000000", "net_amount": 2920, "other_details": { "authcode": "VDhdH5BWz", "cardType": "M/C", "lastFourDigits": "0060" }, "transaction_date": "2024-04-15T12:01:48.000Z", "transaction_id": "txn_f0478a5ffb" } ], "message": "Transaction fetched successfully", "result": true } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/order/sales-return": { "post": { "tags": [ "Transactions" ], "summary": "Return Sale", "description": "Issues a partial or full refund against a completed card transaction. Partial refunds can be applied multiple times as long as the cumulative amount does not exceed the original charge. If the refund amount equals the original amount and the transaction is older than 24 hours, a void is performed automatically. Fires a payment.refund webhook on success.", "operationId": "returnSale", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "merchant_key", "transaction_id" ], "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique API key.", "example": "{{merchant_key}}" }, "transaction_id": { "type": "string", "description": "The pos_guid of the original completed transaction to refund. Must have is_status = 2 (completed).", "example": "txn_a7f0b5340a" }, "amount": { "type": "string", "description": "Amount to refund. Must not exceed the original transaction amount or the remaining refundable balance.", "example": "1.00" }, "sub_merchant_key": { "type": "string", "description": "Sub-merchant key, if applicable.", "example": "" } } }, "examples": { "Partial Refund": { "value": { "merchant_key": "{{merchant_key}}", "transaction_id": "txn_a7f0b5340a", "amount": "1.00" } } } } } }, "responses": { "200": { "description": "Refund processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transaction refunded successfully" }, "data": { "type": "object", "properties": { "sales_id": { "type": "string", "description": "ID of the new refund record.", "example": "txn_a8f83189a5" }, "order_createdfrom": { "type": "string", "description": "Source of the original order.", "example": "API" }, "amount": { "type": "number", "description": "Amount refunded.", "example": 1 }, "txn_id": { "type": "string", "description": "Gateway-level transaction reference ID.", "example": "txn_lyWexIP9z2MJkrBBtscY" }, "txn_date": { "type": "string", "format": "date-time", "description": "Timestamp of the refund.", "example": "2026-06-15T19:13:03.000Z" }, "linked_txn_id": { "type": "string", "description": "ID of the original transaction that was refunded.", "example": "txn_a7f0b5340a" }, "transaction_id": { "type": "string", "description": "Same as sales_id \u2014 the refund record ID.", "example": "txn_a8f83189a5" }, "Status": { "type": "string", "description": "Result of the refund operation.", "example": "Success" }, "type": { "type": "string", "description": "Always Refund.", "example": "Refund" } } } } } } } }, "400": { "description": "Refund failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Amount should not be greater than sales charge amount." } } }, "examples": { "Transaction not found": { "value": { "result": false, "message": "Payment method not found." } }, "Amount exceeds original": { "value": { "result": false, "message": "Amount should not be greater than sales charge amount." } }, "Amount exceeds remaining": { "value": { "result": false, "message": "The amount should not be greater than the remaining amount." } }, "Already fully refunded": { "value": { "result": false, "message": "Refund already done. No refund allowed." } } } } } } }, "security": [ { "basicAuth": [] } ] } }, "/order/sales-void": { "post": { "tags": [ "Transactions" ], "summary": "Void Sale", "description": "Void Sale", "operationId": "voidSale", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "merchant_key": { "type": "string", "description": "The merchant's unique key. Returned in the `merchant_key` field of the get merchants by client call.", "example": "{{merchant_key}}" }, "transaction_id": { "type": "string", "description": "Unique transaction ID. Returned in the `transaction_id` field of the Get Transactions (`GET /merchant/transactions`) response.", "example": "txn_a7f0b5340a" }, "sub_merchant_key": { "type": "string", "example": "" } }, "required": [ "amount", "merchant_key", "transaction_id" ] }, "examples": { "Void Sale": { "value": { "merchant_key": "{{merchant_key}}", "transaction_id": "txn_a7f0b5340a", "sub_merchant_key": "" } } } } } }, "responses": { "200": { "description": "" } }, "security": [ { "basicAuth": [] } ] } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Use your Fractal API credentials.\n\nUsername = Client ID\nPassword = Secret Key\n\nSandbox credentials can be generated from the Test Portal." } } }, "tags": [ { "name": "Merchant Onboarding" }, { "name": "Payment Collection Methods" }, { "name": "Requests" }, { "name": "Preauthorizations" }, { "name": "Customers" }, { "name": "Charging Customer" }, { "name": "Transactions" } ] }