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

TypeValue
Endpoint/api/v2/transactions/
MethodPOST
API ReferenceStore transaction

Body Parameters

ParameterDescription
private_tokenPrivate token.
force_storage_fields_checkIf true, will check if storage fields are present for non-delegated transactions as well.
manual_modeUse manual mode, bypassing country detection. Only allowed with private token. This flag allows the original_transaction_key field to be used.
transactionAny 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"
}