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://services.taxamo.com/api/v2/transactions

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"
}

Did this page help you?