{ "openapi": "3.0.1", "info": { "title": "NoFraud Transaction API", "version": "1", "description": "This documentation explains the endpoints available for building a Custom NoFraud integration into your eCommerce site. \nNoFraud supports a conventional API integration, outlined in here, as well as Apps and Plugins for platforms such as Shopify, BigCommerce, Magento, and Volusion.\n\nAll Custom API integrations require a NoFraud API Key.\nYou can generate an API key within the NoFraud Portal under 'Integrations'. \nRefer to the [Quickstart Guide](guides/quickstart.md) for a step-by-step guide for generating your first API key.\n\nA Custom API integration requires incorporating logic into your platform to make requests to NoFraud's API for order validation. \nThese requests are typically inserted into your order processing flow using one of the following workflows:\n\n1. **Pre-Gateway**: Fraud check sent to NoFraud's API before any information is sent to your payment processor to charge the customer's credit card.\n2. **Pre-Acceptance** Fraud check sent to NoFraud's API immediately after your payment processor authorizes the payment, but before you have served a response, or \"Thank You\" page back to the customer.\n3. **Post-Acceptance**: Fraud check sent to NoFraud's API after you have accepted the order and served your customer a response, or \"Thank You\" page, but before you have fulfilled and shipped the order.\n\nNoFraud's response will contain a fraud decision to be used, in conjunction with custom logic on your end, to either process or cancel the order.\n\nTransactions sent to NoFraud's API both pre-, and post-acceptance must contain the credit card's last four digits as well as the AVS and CVV response codes provided by your gateway.\n\nRefer to [Workflows](guides/workflows.md) for more information about these options including implementation details." }, "paths": { "/transaction": { "post": { "x-swagger-router-controller": "create-transaction", "operationId": "create-transaction", "summary": "Create a transaction", "description": "Request made with transaction information to be screened by NoFraud. The `nf-token` property is the NoFraud API Key for the integration. \nYou can find it on [NoFraud Portal integrations page](https://portal.nofraud.com/integration).\n\nThe body of the request must contain all required fields, as listed below. \nThe addition of any and all optional fields will help improve the accuracy of NoFraud's decisions. \nWe encourage new integrations to include as much data as possible, or available, given your platform and/or payment gateway.\n\nSee [Test Credits Cards](reference/test-credit-cards.md) for cards you can use while testing.\n\nThe response contains the `id` field which is the id of the transaction on NoFraud and the `decision` field which can be:\n * `pass`: Transaction was approved on NoFraud screening.\n * `fail`: Transaction failed.\n * `review`: Transaction needs manual review.\n\nFor orders that receive a `fail` status the `message` field will contain your Custom Error Message, as set in your NoFraud Portal account. \nYou can find this option under your Settings tab.\n\n##### Pre-Gateway Requests\n\nPre-gateway requests must include full credit card information, including the card number, expiration date, and card code. \n\nIn this case, NoFraud will obtain the AVS and CVV response codes manually during our screening process. \n\nWith a pre-gateway integration, you can keep the user on-site in the checkout process, and if NoFraud responds with a `fail` status, the user can be given an error message requesting that they try again to submit the order. \n\nIf an order is unsuccessful in passing NoFraud's screening process, then it can be prevented from being sent to your payment gateway, saving you money in credit card processing fees. \n\nIf an order passes NoFraud's screening, and is then sent to your payment gateway, you will need to make a secondary API call to NoFraud to update our system with the gateway response.\n\n##### Pre- and Post-Acceptance Requests\n\nBoth pre-, and post-acceptance requests must include the AVS and CVV response codes as provided by your payment gateway, as well as the last four digits of the credit card used. \n\nWith both pre-, and post-acceptance integration methods, orders that receive a `fail` decision from NoFraud should be canceled and the credit cards refunded.\n", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "Full Sample": { "value": { "nf-token": "NF_prod_4edbb1f06c68dbcbfd38ce91256de3d8", "amount": "149.95", "shippingAmount": "4.95", "shippingMethod": "UPS Ground", "gatewayName": "Authorize.net", "gatewayStatus": "pass", "cardAttempts": "2", "customerIP": "127.0.0.1", "referialCode": "840cc18f8", "avsResultCode": "U", "cvvResultCode": "1", "cavvResultCode": "A", "currencyCode": "USD", "discountPrice": "5.00", "discountPercentage": "5", "customer": { "id": "1000315", "email": "example@email.com", "joinedOn": "12/01/2025", "lastSignIn": "12/25/2025", "lastPurchaseDate": "12/25/2025", "totalPreviousPurchases": 5, "totalPurchaseValue": 2951.15, "savedCcAddedOn": "12/25/2025" }, "merchant": { "name": "Test Company", "website": "https://www.test-company.com", "email": "email@testcompany.com", "productType": "Goods" }, "order": { "invoiceNumber": "1123581321", "orderType": "one-time", "referringSite": "Google", "referringUrl": "https://www.google.com/search?q=test+company&oq=test+company&sourceid=chrome&ie=UTF-8", "landingPage": "https://www.test-company.com", "landingPageType": "home" }, "payment": { "method": "Credit Card", "creditCard": { "last4": "1111", "cardType": "Visa", "cardNumber": "4111111111111111", "expirationDate": "0923", "cardCode": "999", "bin": "411111" } }, "travel": { "travelDate": "12/31/2025", "destination": "Denver, CO", "pointOfOrigin": "Seattle, WA" }, "billTo": { "firstName": "John", "lastName": "Smith", "company": "Some Company", "address": "123 Broadway Apt #1", "city": "New York", "state": "NY", "zip": "11001", "country": "US", "phoneNumber": "1112223333" }, "shipTo": { "firstName": "Fred", "lastName": "Smith", "company": "Another Company", "address": "4321 Ave A", "city": "Denver", "state": "CO", "zip": "80210", "country": "US" }, "lineItems": [ { "sku": "12345", "name": "Example Product 1", "price": 37.36, "quantity": 3, "category": "Example Category 1", "manufacturer": "Example Manufacturer 1", "notes": "Example Notes 1" }, { "sku": "23456", "name": "Example Product 2", "price": 37.87, "quantity": 1, "category": "Example Category 2", "manufacturer": "Example Manufacturer 2", "notes": "Example Notes 2" } ], "userFields": { "field1": "value1", "field2": "value2" } } }, "Minimal Pre-Gateway": { "value": { "nf-token": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6", "customer": { "email": "example@email.com" }, "billTo": { "firstName": "John", "lastName": "Smith", "address": "123 Broadway Apt", "city": "New York", "state": "NY", "zip": "11001", "country": "US", "phoneNumber": "1112223333" }, "customerIP": "127.0.0.2", "amount": "50", "payment": { "creditCard": { "cardNumber": "4111111111111111", "expirationDate": "0929", "cardCode": "999" } } } }, "Minimal Pre/Post-Acceptance": { "value": { "nf-token": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6", "customer": { "email": "example@email.com" }, "billTo": { "firstName": "John", "lastName": "Smith", "address": "123 Broadway Apt", "city": "New York", "state": "NY", "zip": "11001", "country": "US", "phoneNumber": "1112223333" }, "customerIP": "127.0.0.2", "amount": "50", "avsResultCode": "U", "cvvResultCode": "1", "payment": { "creditCard": { "last4": "9999" } } } } } } } }, "responses": { "200": { "description": "Successful request. Response body will contain a standard or enriched transaction payload depending on whether the request set `enrich` as true.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TransactionPayloadResponse" }, { "$ref": "#/components/schemas/EnrichedTransactionPayloadResponse" } ], "example": { "id": "3317d310-1b4f-4d98-bd7d-44121ded2158", "decision": "pass" } } } } }, "400": { "description": "No value for billTo field. It can be an empty object but property needs to be defined.", "content": { "application/json": { "example": { "Errors": [ "Missing data, billTo field" ] } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/gateway_response": { "post": { "x-swagger-router-controller": "gateway_response", "operationId": "gateway_response", "summary": "Update gateway response", "description": "Request made by custom integrations after the creation of the initial transaction to send the result from the payment gateway. \nThe `nf-token` property is the NoFraud API Key, you can find it on [NoFraud Portal integrations page](https://portal.nofraud.com/integration).\n\nThe `nf-id` value is the `id` returned from the `POST /transaction` request.\n\nThis step is only required if the initial API call to NoFraud was completed before the corresponding transaction was sent to your payment gateway. \nIn such cases, this API call should be sent to NoFraud after you receive a response from the gateway. \nThe purpose of this API call is to provide NoFraud with the appropriate gateway information our system did not have access to during the initial API call.\n\nDifferent payment gateways provide different result responses. \nYou may need to format this field to match NoFraud's accepted values (e.g. \"approved\" should be converted to `pass`, \"declined\" should be converted to `fail`, etc.)", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayResponseBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "Status": "OK" } } } }, "400": { "description": "Invalid or empty nf-id", "content": { "application/json": { "examples": { "IDNotDefined": { "value": { "Errors": [ "nf-id field is not defined." ] } }, "IDEmptyOrMalformed": { "value": { "Errors": [ "nf-id value is empty or malformed. please send the id of the response you received from the inital transaction from nofraud here." ] } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/status/{nf-token}/{transaction-id-or-invoice-number}": { "get": { "x-swagger-router-controller": "status", "operationId": "status", "summary": "Get transaction status", "description": "Get transaction status by transaction ID (URL) or invoice/order number.\n\nUtilizing this endpoint can be helpful in automating the process by which your system handles NoFraud's `review` orders. \nYour system can be configured to collect and hold all review orders upon receiving them. \nThen, an automated cron, or other similar system, can be configured to send requests to this endpoint at set intervals, in order to determine if the review order has had a status update to `pass`, `fail`, or `fraudulent`. \nWhen your system identifies a status update for a particular transacation, that transaction can either be processed and shipped, in the event of a `pass`, or canceled and refunded, in the event of either a \"fail\" or \"fraudulent\" status update.\n\nIf invoice/order numbers for your transactions appear in the NoFraud Portal with a preceeding number sign \"#\", the ID should be included in the HTTP GET request without this character. \nFor example, if the order number in NoFraud appears as \"#10205793\", the order number should be included in the request as simply \"10205793\".\n\nIf more than one transaction appears in NoFraud's system with the included invoice/order number, this process will only check the first such transaction in our system with this invoice/order number.", "parameters": [ { "in": "path", "name": "nf-token", "example": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6", "description": "NoFraud API Key - Integration Token", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "transaction-id-or-invoice-number", "example": "16eb5701-d411-525d-abd4-4985fa05f187", "description": "Transaction uuid received on order creation or the invoice number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/TransactionResponse" }, "403": { "$ref": "#/components/responses/Unauthorized" } } } }, "/status_by_url/{nf-token}/{transaction-id}": { "get": { "x-swagger-router-controller": "status_by_url", "operationId": "status_by_url", "summary": "Get transaction status by ID", "description": "Get transaction status by transaction ID (URL)\n\nUtilizing this endpoint can be helpful in automating the process by which your system handles NoFraud's `review` orders. \nYour system can be configured to collect and hold all review orders upon receiving them. \nThen, an automated cron, or other similar system, can be configured to send requests to this endpoint at set intervals, in order to determine if the review order has had a status update to `pass`, `fail`, or `fraudulent`. \nWhen your system identifies a status update for a particular transacation, that transaction can either be processed and shipped, in the event of a `pass`, or canceled and refunded, in the event of either a \"fail\" or \"fraudulent\" status update.", "parameters": [ { "in": "path", "name": "nf-token", "description": "NoFraud API Key - Integration Token", "required": true, "example": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6", "schema": { "type": "string" } }, { "in": "path", "name": "transaction-id", "example": "16eb5701-d411-525d-abd4-4985fa05f187", "description": "Transaction id received on transaction creation payload", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/TransactionResponse" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Transaction not found", "content": { "application/json": { "example": { "Errors": [ "Transaction Not Found" ] } } } } } } }, "/status_by_invoice/{nf-token}/{invoice-id}": { "get": { "x-swagger-router-controller": "status_by_invoice", "operationId": "status_by_invoice", "summary": "Get transaction status by invoice/order", "description": "Get transaction status by invoice/order ID.\n\nUtilizing this endpoint can be helpful in automating the process by which your system handles NoFraud's `review` orders. \nYour system can be configured to collect and hold all review orders upon receiving them. \nThen, an automated cron, or other similar system, can be configured to send requests to this endpoint at set intervals, in order to determine if the review order has had a status update to `pass`, `fail`, or `fraudulent`. \nWhen your system identifies a status update for a particular transacation, that transaction can either be processed and shipped, in the event of a `pass`, or canceled and refunded, in the event of either a \"fail\" or \"fraudulent\" status update.\n\nIf invoice/order numbers for your transactions appear in the NoFraud Portal with a preceeding number sign \"#\", the ID should be included in the HTTP GET request without this character. \nFor example, if the order number in NoFraud appears as \"#10205793\", the order number should be included in the request as simply \"10205793\".\n\nIf more than one transaction appears in NoFraud's system with the included invoice/order number, this process will only check the first such transaction in our system with this invoice/order number.", "parameters": [ { "in": "path", "name": "nf-token", "description": "NoFraud API Key - Integration Token", "required": true, "example": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6", "schema": { "type": "string" } }, { "in": "path", "name": "invoice-id", "example": 10205793, "description": "Invoice/order ID included in transaction creation payload.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/TransactionResponse" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Transaction not found.", "content": { "application/json": { "example": { "Errors": [ "Transaction Not Found" ] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "Unauthorized": { "description": "Invalid nf-token", "content": { "application/json": { "example": { "Errors": [ "Not Authorized" ] } } } }, "TransactionResponse": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPayloadResponse" } } }, "links": { "SetTransactionId": { "operationId": "gateway_response", "x-requestBodyParameters": { "nf-id": "$response.body#/id" }, "requestBody": { "nf-id": "$response.body#/id" }, "description": "The `transaction-id` value returned in the response can be used as `nf-id` parameter in `POST /gateway_status` `nf-id` request body\n" } } }, "EnrichedTransactionResponse": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedTransactionPayloadResponse" } } } } }, "schemas": { "Transaction": { "description": "

", "required": [ "nf-token", "billTo", "amount", "customerIP", "customer", "payment" ], "properties": { "nf-token": { "type": "string", "description": "NoFraud API key for authentication.", "example": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6" }, "amount": { "type": "string", "description": "Total amount paid for order (including shipping, taxes, and any additional fees). Must be a valid, non-negative number. Cannot exceed 24 characters.", "maxLength": 24, "pattern": "^\\d*\\.?\\d*$", "example": "30.23" }, "currency_code": { "type": "string", "description": "Three-letter country or currency code. System assumes transaction amount is in USD if not present. [View Supported Country Codes](reference/supported-country-codes.md). [View Supported Currency Codes](reference/supported-currency-codes.md). Cannot exceed 3 characters.", "maxLength": 3, "example": "USD" }, "discountAmount": { "type": "string", "description": "Discount or coupon amount. Used to denote a discount or coupon code was used for the specified dollar amount.", "pattern": "^\\d*\\.?\\d*$", "example": "30.23" }, "discountPrice": { "type": "string", "description": "Discount or coupon amount. Used to denote a discount or coupon code was used for the specified dollar amount.", "pattern": "^\\d*\\.?\\d*$", "example": "30.23" }, "discountPercentage": { "type": "string", "description": "Discount or coupon percentage. Used to denote a discount or coupon code was used for the specified percentage off.", "pattern": "^\\d*\\.?\\d*$", "example": "25.00" }, "shippingAmount": { "type": "string", "description": "Amount paid for shipping. Very helpful for optimal results. Must be a valid, non-negative number. Cannot exceed 24 characters.", "maxLength": 24, "pattern": "^\\d*\\.?\\d*$", "example": "30.23" }, "shippingMethod": { "type": "string", "description": "Shipping method used for transaction. Can be used to describe the method used for shipping (i.e. \"UPS Ground\", \"Fed-Ex Overnight\", etc.).", "example": "FedEx 3-day" }, "fulfillmentDate": { "type": "string", "description": "Future date product or service will be fulfilled. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "example": "02/23/2030", "maxLength": 128 }, "checkout": { "$ref": "#/components/schemas/Checkout" }, "customer": { "$ref": "#/components/schemas/Customer" }, "merchant": { "$ref": "#/components/schemas/Merchant" }, "order": { "$ref": "#/components/schemas/OrderInfo" }, "payment": { "$ref": "#/components/schemas/Payment" }, "travel": { "$ref": "#/components/schemas/Travel" }, "billTo": { "description": "Required field but can be an empty object", "allOf": [ { "$ref": "#/components/schemas/BillTo" } ] }, "shipTo": { "description": "Optional unless merchant object is present and productType is \"Goods\".", "allOf": [ { "$ref": "#/components/schemas/ShipTo" } ] }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" }, "example": [ { "sku": "123", "manufacturer": "M1", "name": "Test Product 1", "category": "Test Products", "price": 50, "quantity": 2 }, { "sku": "456", "manufacturer": "M2", "name": "Test Product 2", "category": "Test 2 Products", "price": "52.00", "quantity": "1" } ] }, "gatewayName": { "type": "string", "example": "Gateway Name" }, "gatewayStatus": { "type": "string" }, "transaction-id": { "type": "string", "readOnly": true }, "authcode": { "type": "string", "readOnly": true }, "customerIP": { "type": "string", "example": "123.456.7.8" }, "avsResultCode": { "type": "string", "maxLength": 3, "description": "Required for pre-, and post-acceptance integrations if payment object is missing. Cannot exceed 3 characters.", "example": "U" }, "cvvResultCode": { "type": "string", "maxLength": 1, "description": "Required for pre-, and post-acceptance integrations if payment object is missing. Must be a valid, single uppercase alphanumeric character.", "example": "M" }, "cavvResultCode": { "type": "string", "enum": [ "", "A", "B", "C", "D", "I", "U", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" ], "maxLength": 1, "description": "Uppercase letters or numbers", "example": "A" }, "3d_secure": { "type": "object", "properties": { "authenticated": { "type": "boolean", "example": true }, "succeeded": { "type": "boolean", "example": true }, "version": { "type": "string" } } }, "card_attempts": { "type": "string", "example": "0", "description": "Integer value representing attempts with same card" }, "referial_code": { "type": "string", "pattern": "^[0-9A-Fa-f]+$", "maxLength": 64 }, "app": { "type": "string", "example": "my_app" }, "version": { "type": "string" }, "appName": { "type": "string" }, "appVersion": { "type": "string" }, "userFields": { "type": "object", "description": "User field information object. Can include any and all additional information that would be helpful for manual review." }, "performance": { "type": "object" }, "digitalGoodsAmount": { "type": "string" }, "digitalGoodsPercentage": { "type": "string" }, "gatewayType": { "type": "string", "enum": [ "post-gateway", "pre-gateway" ] }, "isBopis": { "type": "string", "description": "Indicates if it's a \"buy online, pickup in store\" type of order\n" }, "enrich": { "type": "boolean", "description": "Flag added to call to request an expanded response payload with additional information such as insights, sub-status, and other relevant details. Enabling this option provides a more detailed and comprehensive response.\n" }, "subscriptionDetails": { "$ref": "#/components/schemas/SubscriptionDetails" } } }, "TransactionPayloadResponse": { "description": "OK", "type": "object", "required": [ "id", "decision" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier of the transaction with our API. Transaction can be found at portal.nofraud.com/transaction/{id} the id being this field." }, "decision": { "type": "string", "description": "What NoFraud decided for this transaction.", "example": "pass", "enum": [ "pass", "fail", "review", "fraudulent", "error" ] }, "message": { "type": "string", "description": "Custom error message. Only included in responses with a \"fail\" decision based off of the Custom Error Message field set for your NoFraud Portal account" } } }, "EnrichedTransactionPayloadResponse": { "description": "Payload", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "decision": { "type": "string", "example": "pass", "enum": [ "pass", "fail", "review", "fraudulent", "error" ] }, "account_mode": { "readOnly": true, "type": "string", "enum": [ "live", "test" ] }, "passive_mode": { "readOnly": true, "type": "boolean" }, "sub_status": { "readOnly": true, "type": "string" }, "insights": { "type": "object", "properties": { "risk": { "type": "object", "properties": { "1": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ] } } } } }, "trust": { "type": "object", "properties": { "1": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ] } } } } }, "neutral": { "type": "object", "properties": { "1": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } } } } }, "recommendation": { "type": "object", "properties": { "1": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } } } } } } } } }, "BillTo": { "required": [ "firstName", "lastName", "address", "city", "state", "zip", "country", "phoneNumber" ], "properties": { "firstName": { "type": "string", "description": "Billing first name. Cannot exceed 128 characters.", "maxLength": 128, "example": "John" }, "lastName": { "type": "string", "description": "Billing last name. Cannot exceed 128 characters.", "maxLength": 128, "example": "Doe" }, "company": { "type": "string", "description": "Billing company name. Cannot exceed 128 characters.", "maxLength": 128, "example": "NoFraud" }, "address": { "type": "string", "description": "Billing street address. Should include the building number, street name, and unit or apartment number (if present). Cannot exceed 128 characters.", "maxLength": 128, "example": "2615 Ln. Autumn Abbot" }, "city": { "type": "string", "description": "Billing city. Cannot exceed 128 characters.", "maxLength": 128, "example": "San Antonio" }, "state": { "type": "string", "description": "Billing state. Cannot exceed 128 characters.", "maxLength": 128, "example": "TX" }, "zip": { "type": "string", "description": "Billing zip or postal code. Cannot exceed 128 characters.", "maxLength": 128, "example": "78257" }, "country": { "type": "string", "description": "Billing country. Must be a valid ISO 2-character Country Code.", "example": "US" }, "phoneNumber": { "type": "string", "description": "Billing phone number. Should be a valid phone number.", "example": "78981031212" } } }, "ShipTo": { "required": [ "firstName", "lastName", "address", "city", "state", "zip", "country" ], "properties": { "firstName": { "type": "string", "description": "Shipping first name. Required only if `shipTo` object is required. Cannot exceed 128 characters.", "maxLength": 128, "example": "John" }, "lastName": { "type": "string", "description": "Shipping last name. Required only if `shipTo` object is required. Cannot exceed 128 characters.", "maxLength": 128, "example": "Doe" }, "company": { "type": "string", "description": "Shipping company name. Cannot exceed 128 characters.", "maxLength": 128, "example": "NoFraud" }, "address": { "type": "string", "description": "Shipping street address. Required only if `shipTo` object is required. Should include the building number, street name, and unit or apartment number (if present). Cannot exceed 128 characters.", "example": "2615 Ln. Autumn Abbot", "maxLength": 128 }, "city": { "type": "string", "description": "Shipping city. Required only if `shipTo` object is required. Cannot exceed 128 characters.", "maxLength": 128, "example": "San Antonio" }, "state": { "type": "string", "description": "Shipping state. Required only if `shipTo` object is required. Cannot exceed 128 characters.", "maxLength": 128, "example": "TX" }, "zip": { "type": "string", "description": "Shipping zip or postal code. Required only if `shipTo` object is required. Cannot exceed 128 characters.", "maxLength": 128, "example": "78257" }, "country": { "type": "string", "description": "Shipping country. Required only if `shipTo` object is required. Must be a valid ISO 2-character Country Code.", "example": "US" } } }, "OrderInfo": { "properties": { "invoiceNumber": { "type": "string", "description": "Invoice number of this order. Cannot exceed 64 characters.", "maxLength": 64, "example": "1634123" }, "order_type": { "type": "string", "description": "The type of order. Should be of the following: `one-time`, `recurring`, `subscription`, or `upsell`. If blank, our system will assume the order is a `one-time` purchase." }, "referring_site": { "type": "string", "description": "The name of the site where the customer was referred or redirected to your site (e.g. 'Google', 'Facebook', 'Yelp', etc.)" }, "referring_url": { "type": "string", "description": "The URL of the page where the customer was referred or redirected to your site." }, "landing_page": { "type": "string", "description": "The URL of the page on your site which the customer first visited." }, "landing_page_type": { "type": "string", "description": "The type of page which the customer first visited on your site. Should be one of the following: `home`, `product`, `search`, `category`, `about`, or `other`." } } }, "Payment": { "type": "object", "required": [ "creditCard" ], "properties": { "method": { "type": "string", "description": "Method used for payment. Can be used to denote the specific method used for payment (i.e. 'PayPal', 'Amazon Pay', 'Gift Card', etc.). System will assume a credit card was used if the payment.creditCard object is present.", "example": "creditCard" }, "creditCard": { "$ref": "#/components/schemas/CreditCard" } } }, "Merchant": { "required": [ "name", "email", "website" ], "properties": { "name": { "type": "string", "description": "Merchant company or eCommerce store name. Cannot exceed 128 characters.", "maxLength": 128, "example": "Test Integration" }, "website": { "type": "string", "description": "URL or website for merchant's eCommerce store. Must be a [Fully Qualified Domain Name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name). Cannot exceed 128 characters.", "example": "www.yourwebsite.com" }, "email": { "type": "string", "description": "Merchant's email. Must be a valid email. Cannot exceed 128 characters.", "maxLength": 128, "format": "email" }, "productType": { "type": "string", "description": "The type of product the merchant is selling. Should be either `Goods` or `Services`. Cannot exceed 128 characters.", "maxLength": 128, "example": "Services" } } }, "Customer": { "required": [ "email" ], "properties": { "id": { "type": "string", "description": "Merchant's ID for this customer. Cannot exceed 64 characters.", "maxLength": 64, "example": "123" }, "email": { "type": "string", "description": "Customer's email address. Must be a valid email. Cannot exceed 128 characters.", "maxLength": 128, "format": "email", "example": "pass@nofraud.com" }, "joined_on": { "type": "string", "description": "Date customer created account. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "maxLength": 128 }, "last_sign_in": { "type": "string", "description": "Date of most-recent sign-in to customer's account. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "maxLength": 128 }, "last_purchase_date": { "type": "string", "description": "Date of most recent purchase made by customer. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "maxLength": 128 }, "total_previous_purchases": { "type": "string", "description": "Total number of previous purchases made by customer. Must be a valid, nonegative number.", "example": "12" }, "total_purchase_value": { "type": "string", "description": "Total value of all previous purchases made by customer. Must be a valid, nonengative number.", "example": "1230.21" }, "saved_cc_added_on": { "type": "string", "description": "Date customer saved credit card used for purchase. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "maxLength": 128 } } }, "LineItem": { "properties": { "sku": { "type": "string", "description": "SKU or item number for product." }, "manufacturer": { "type": "string", "description": "Product manufacturer." }, "name": { "type": "string", "description": "Product name." }, "category": { "type": "string", "description": "Product category." }, "notes": { "type": "string", "description": "Product notes or description." }, "price": { "type": "number", "description": "Price or cost of one product." }, "quantity": { "type": "number", "description": "Product quantity." }, "sellingPlanName": { "type": "string" }, "sellingPlanId": { "type": "string" } } }, "CreditCard": { "properties": { "bin": { "type": "string", "example": "4111111" }, "last4": { "type": "string", "description": "Required if following Pre- or Post-Acceptance workflow. Last 4 digits of credit card number used for purchase. Must be exactly four characters and contain only valid numerical digits.", "pattern": "^\\d+$", "maxLength": 4, "minLength": 4 }, "cardType": { "type": "string", "description": "Credit card type (ex. Visa, Mastercard, etc.).", "example": "visa" }, "cardNumber": { "type": "string", "description": "Required if AVS and CVV result codes are missing. Must be a full, valid credit card number. Test credit cards cannot be used if account is live and real credit cards cannot be used if your account is in test mode." }, "expirationDate": { "type": "string", "example": "02/2050", "description": "Required if AVS and CVV result codes are missing. Must be in one of the following formats: 'MMYY', 'MM-YY', 'MM-YYYY', 'MM/YYYY', 'MM/YY'. Must be a valid date that is not expired." }, "cardCode": { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[0-9]+$", "description": "Required if AVS and CVV result codes are missing. Must be either 3 or 4 characters and contain only valid, numerical digits." } } }, "Amount": { "type": "string", "pattern": "^\\d*\\.?\\d*$", "example": "30.23" }, "Travel": { "type": "object", "readOnly": true, "properties": { "travel_date": { "type": "string", "description": "Date of travel. 'MM/DD/YYYY' format. Cannot exceed 128 characters.", "maxLength": 128, "example": "02/20/2023" }, "destination": { "type": "string", "description": "Travel destination address, city, region, or location. Cannot exceed 128 characters.", "maxLength": 128 }, "point_of_origin": { "type": "string", "description": "Travel point of origin address, city, region, or location. Cannot exceed 128 characters.", "maxLength": 128 } } }, "GatewayResponseBody": { "type": "object", "required": [ "nf-token", "nf-id" ], "properties": { "nf-token": { "type": "string", "description": "API key for authentication.", "example": "NF_prod_eda02a1aa67099c0f30b3ab937bce2a6" }, "nf-id": { "type": "string", "description": "Transaction ID of the decision we returned to you.", "format": "uuid", "example": "16f235a0-e4a3-529c-9b83-bd15fe722110" }, "gateway-response": { "$ref": "#/components/schemas/GatewayResponse" } } }, "GatewayResponse": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "string", "description": "Result of the transaction as provided by the gateway", "example": "pass", "enum": [ "pass", "fail", "error", "review" ] }, "authcode": { "type": "string", "description": "Authorization code of the transaction from the gateway.", "example": "000000" }, "transaction-id": { "type": "string", "description": "ID of the transaction from the gateway.", "example": "10010234578" } } }, "Checkout": { "type": "object", "readOnly": true, "properties": { "flow": { "type": "string", "example": "shipping" }, "sessionId": { "type": "string", "example": "AAAABBBB-CCCC-DDDD-EEEE-FFFFGGGGHHHH" }, "deviceCookie": { "type": "string", "example": "AAAABBBB-CCCC-DDDD-EEEE-FFFFGGGGHHHH" } } }, "SubscriptionDetails": { "type": "object", "properties": { "sumOfOrders": { "type": "number", "example": 3 }, "firstOrderDate": { "type": "string", "example": "2022-02-03" }, "daysSinceFirstOrder": { "type": "number", "example": 30 }, "daysSinceLastOrder": { "type": "number", "example": 1 }, "priorAddress": { "type": "string", "example": "St. 1, New York, 10001" }, "quantityOfOrders": { "type": "number", "example": 31 }, "frequencyInDays": { "type": "number", "example": 1 }, "lastOrderDate": { "type": "string", "example": "2022-02-03" }, "firstOrderIp": { "type": "string", "example": "127.0.0.1" }, "firstOrderId": { "type": "string", "example": "gid://shopify/Order/5269077557313" }, "lastOrderId": { "type": "string", "example": "gid://shopify/Order/5269077557313" } } } } }, "servers": [ { "description": "Production", "url": "https://api.nofraud.com" }, { "description": "Test", "url": "https://apitest.nofraud.com" } ] }