Store transaction

Use this request to store a transaction and return a Transaction Key.

To store a transaction, use a POST method and the following URL:

https://{service_url}/api/v2/transactions

where {service_url} is the URL of the service's environment.

Details

Type	Value
Endpoint	`/api/v2/transactions/`
Method	POST
API Reference	Store transaction

Body Parameters

Parameter	Description
private_token	Private token.
force_storage_fields_check	If true, will check if storage fields are present for non-delegated transactions as well.
manual_mode	Use manual mode, bypassing country detection. Only allowed with private token. This flag allows the original_transaction_key field to be used.
transaction	Any transaction details that you wish to include. For more information, see Transaction Schema.

Request Example

The following example shows how you can send information in the body of this request:

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
      "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "buyer_ip": "109.121.15.46",
          "currency_code": "EUR",
          "billing_country_code": "BE",
          "buyer_credit_card_prefix": "424242424"
      },
      "private_token": "priv_***********"
  }' \
 'https://services.taxamo.com/api/v2/transactions'

Response Examples

The following example shows a successful response where the tax is supported (tax_supported=true):

{
    "is_delegated": false,
    "transaction": {
        "amount": 100.0,
        "custom_fields": [],
        "kind": "sa-b2c",
        "tax_supported": true,
        "tax_country_codes": "SA",
        "key": "TPmgAAEa9QlysHxE3niZdjIZEMu0",
        "tax_amount": 5.0,
        "tax_deducted": false,
        "tax_region": "SA",
        "billing_country_code": "SA",
        "merchant_id": 18109,
        "evidence": {
            "by_billing": {
                "evidence_value": "SA",
                "used": true,
                "resolved_country_code": "SA",
                "evidence_type": "by-billing"
            },
            "by_payment_method": {
                "evidence_value": "SA",
                "used": true,
                "resolved_country_code": "SA",
                "evidence_type": "by-payment-method"
            }

        },
        "invoice_place": "Default place for test mode",
        "create_timestamp": "2019-09-26T09:35:00Z",
        "additional_currencies": {
            "invoice": {
                "currency_code": "SAR",
                "fx_rate": 3.75,
                "amount": 375.0,
                "tax_amount": 18.75,
                "total_amount": 393.75
            }
        },
        "tax_country_code": "SA",
        "countries": {
            "by_billing": {
                "code": "SA",
                "tax_supported": true,
                ...
            },
            "by_payment_method": {
                "code": "SA",
                "tax_supported": true,
                ...
            },
            "detected": {
                "code": "SA",
                "tax_supported": true,
                ...
            }
        },
        "transaction_lines": [
            {
                "amount": 100.0,
                "unit_price": 100.0,
                "tax_supported": true,
                "tax_amount": 5.0,
                "tax_deducted": false,
                "tax_region": "SA",
                "tax_rate": 5,
                "additional_currencies": {
                    "invoice": {
                        "fx_rate": 3.75,
                        "amount": 375.0,
                        "currency_code": "SAR",
                        "total_amount": 393.75,
                        "tax_amount": 18.75
                    }
                },
                "tax_country_code": "SA",
                "line_key": "oovqA-2G58vE4KFR",
                "custom_id": "1",
                "tax_name": "VAT",
                "line_num": 1,
                "deducted_tax_amount": 0.0,
                "quantity": 1.0,
                "total_amount": 105.0,
                "deducted_tax_rate": 0,
                "tax_entity_name": "Saudi Arabia"
            }
        ],
        "buyer_ip": "",
        "manual": false,
        "country_name": "Saudi Arabia",
        "product_classes": "D",
        "fully_informative": false,
        "tax_engine": "taxamo",
        "status": "N",
        "order_date_type": "timestamp",
        "update_timestamp": 1569490500882,
        "shipment_country_data": {},
        "deducted_tax_amount": 0.0,
        "order_date": "2019-09-26T09:35:00Z",
        "invoice_capable": false,
        "total_amount": 105.0,
        "tax_timezone": "GMT",
        "test": true,
        "tax_entity_id": -190001,
        "tax_entity_name": "Saudi Arabia",
        "tax_location_id": -1900001,
        "currency_code": "USD"
    },
    "tax_required_fields": [],
    "storage_required_fields": []
}

The following example shows a successful response where the tax is not supported (tax_supported=false):

{
    "is_delegated": false,
    "transaction": {
        "amount": 100.0,
        "custom_fields": [
            {
                "key": "adsfsaf",
                "value": "1"
            }
        ],
        "kind": "untaxed",
        "tax_supported": false,
        "tax_country_codes": "BR",
        "key": "TMREAAEa9gZysHy7eMYpdjIeqD74",
        "tax_amount": 0,
        "tax_deducted": false,
        "billing_country_code": "BR",
        "merchant_id": 18109,
        "evidence": {
            "by_payment_method": {
                "evidence_value": "BR",
                "resolved_country_code": "BR",
                "used": true,
                "evidence_type": "by-payment-method"
            },
            "by_billing": {
                "evidence_value": "BR",
                "used": true,
                "resolved_country_code": "BR",
                "evidence_type": "by-billing"
            }
        },
        "invoice_place": "Default place for test mode",
        "create_timestamp": "2019-09-26T09:40:58Z",
        "tax_country_code": "BR",
        "countries": {
            "by_billing": {
                "code": "BR",
                "tax_supported": false,
                ...
            },
            "by_payment_method": {
                "code": "BR",
                "tax_supported": false,
                ...
            },
            "detected": {
                "code": "BR",
                "tax_supported": false,
                ...
            }
        },
        "transaction_lines": [
            {
                "amount": 100.0,
                "unit_price": 100,
                "tax_supported": false,
                "tax_deducted": false,
                "tax_country_code": "BR",
                "line_key": "OwJcD-S9OrssONfN",
                "custom_id": "1",
                "line_num": 1,
                "deducted_tax_amount": 0,
                "quantity": 1,
                "total_amount": 100.0,
                "deducted_tax_rate": 0
            }
        ],
        "buyer_ip": "",
        "manual": false,
        "country_name": "Brazil",
        "product_classes": "D",
        "fully_informative": false,
        "status": "N",
        "order_date_type": "timestamp",
        "update_timestamp": 1569490858903,
        "shipment_country_data": {},
        "deducted_tax_amount": 0,
        "order_date": "2019-09-26T09:40:58Z",
        "invoice_capable": false,
        "total_amount": 100.0,
        "tax_timezone": "GMT",
        "test": true,
        "currency_code": "USD"
    },
    "tax_required_fields": [],
    "storage_required_fields": []
}

Error Code Response Examples

The following example response is due to a 400 message where the error is error_code=missing_tax_required_fields:

{
    "errors": [
        "Please provide invoice_address.region."
    ],
    "error_code": "missing_tax_required_fields",
    "tax_supported": true,
    "tax_country_code": "CA",
    "tax_region": "CA",
    "tax_required_fields": [
        {
            "field_name": "invoice_address.region"
        }
    ],
    "storage_required_fields": [
        {
            "field_name": "invoice_address.city"
        },
        {
            "field_name": "invoice_address.postal_code"
        }
    ],
    "evidence": {
        "by_payment_method": {
            "evidence_value": "CA",
            "resolved_country_code": "CA",
            "used": true,
            "evidence_type": "by-payment-method"
        },
        "by_billing": {
            "evidence_value": "CA",
            "used": true,
            "resolved_country_code": "CA",
            "evidence_type": "by-billing"
        }
    },
    "countries": {
        "by_payment_method": {
            "code": "CA",
            "tax_supported": true,
            ...
        },
        "by_billing": {
            "code": "CA",
            "tax_supported": true,
            ...
        },
        "detected": {
            "code": "CA",
            "tax_supported": true,
            ...
        }
    },
    "product_classes": "D",
    "currency_code": "USD"
}

The following example response is due to a 400 message where the error is error_code=no_matching_evidence:

{
    "errors": [
        "Couldn't determine user's country based on provided details."
    ],
    "error_code": "no_matching_evidence",
    "custom_fields": [],
    "tax_deducted": false,
    "billing_country_code": "FR",
    "evidence": {
        "by_payment_method": {
            "evidence_value": "BR",
            "resolved_country_code": "BR",
            "used": false,
            "evidence_type": "by-payment-method"
        },
        "by_billing": {
            "evidence_value": "FR",
            "used": false,
            "resolved_country_code": "FR",
            "evidence_type": "by-billing"
        }
    },
    "countries": {
        "by_payment_method": {
            "code": "BR",
            "tax_supported": false,
            ...
        },
        "by_billing": {
            "code": "FR",
            "tax_supported": true,
            ...
        }
    },
    "transaction_lines": [
        {
            "custom_id": "1",
            "amount": 100,
            "total_amount": null,
            "quantity": null,
            "tax_rate": null,
            "unit_price": null,
            "tax_country_code": null
        }
    ],
    "buyer_ip": "",
    "refunded_tax_amount": 0,
    "country_name": null,
    "refunded_total_amount": 0,
    "order_date_type": "timestamp",
    "order_date": "2019-09-26T10:43:48Z",
    "tax_timezone": "Europe/Dublin",
    "currency_code": "USD"
}

The following example response is due to a 400 message where the error is error_code=validation_error:

{
    "errors": [
        "Unknown currency."
    ],
    "error_code": "validation_error"
}