# Create a transaction

API for creating new payment requests, this API create [Transaction Entity](/sensepay/transaction-api/models/transaction-model.md).

### API Interface

## Creating a new transaction object (Payment Request)

<mark style="color:green;">`POST`</mark> `https://api.sensepass.com/api/transactions/init`

This API creates new payment request based on the fields below.

**Authentication Request Body fields**

[See here our Authentication page](/sensepay/transaction-api/authentication.md)

#### Request Body

<table><thead><tr><th width="210">Name</th><th width="99" data-type="checkbox">Required</th><th width="102">Type</th><th>Description</th></tr></thead><tbody><tr><td>methodType</td><td>false</td><td>string</td><td>Transaction Type:<br>0. 'payment' = Regular Payment<br>1. 'tokenize' = Tokenization<br>2. 'authorize' = Authorization<br>3. 'credit' = Credit transaction (Refund transaction without a reference to original payment transaction)</td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>true</td><td>number</td><td><p>The required amount for this transaction (Cents). </p><p>If products are a part of the transaction - they are all summed up &#x26; calculated via the following formula: </p><p>(amount + vat - discount) * quantity e.g. (10 + 1.7 - 1) * 2.</p></td></tr><tr><td>isCent</td><td>false</td><td>boolean</td><td>Determines if Amount represents in cents or not</td></tr><tr><td>timeOut</td><td>false</td><td>number</td><td>Time until the transaction will be timed out (seconds)</td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>true</td><td>string</td><td>[ USD, CAD, ILS, EUR, RUB ]</td></tr><tr><td>maxInstallments</td><td>false</td><td>number</td><td>Installments Limit for this transaction - Valid only for credit card payment</td></tr><tr><td>returnURL</td><td>false</td><td>string</td><td>URL to redirect consumer after Success or Error (For E-Commerce Transactions)</td></tr><tr><td>cancelURL</td><td>false</td><td>string</td><td>URL to redirect consumer on cancel event from consumer (For E-Commerce Transactions)</td></tr><tr><td>callbackURL</td><td>false</td><td>string</td><td>URL to Callback/webhooks API - SensePass will call this API with full Transaction Entity for every status change about this transaction</td></tr><tr><td>posData</td><td>false</td><td>object</td><td>Any data (object/array/string/number etc...) to be received in the callback url or transaction's responses</td></tr><tr><td>clientPhoneNumber</td><td>false</td><td>string</td><td><p>SMS message will be sent to this consumer number for SMS payment</p><p>For delivery status - See "SMS" field in <a data-mention href="/pages/btqHU8nJb3gaOZCHlURj#transaction-entity">/pages/btqHU8nJb3gaOZCHlURj#transaction-entity</a></p></td></tr><tr><td>clientEmail</td><td>false</td><td>string</td><td>email message will be sent to this consumer email for remote payment</td></tr><tr><td>clientName</td><td>false</td><td>string</td><td>consumer name for the payment</td></tr><tr><td>reason</td><td>false</td><td>string</td><td>The reason for this payment - This field will be presented to the consumer</td></tr><tr><td>invoice</td><td>false</td><td>object</td><td><p>Used to present invoice for the consumer before the payment</p><p>See invoice object entity: <a data-mention href="/pages/0Dvum30l6KS8Sa3JDTuH#invoice-entity">/pages/0Dvum30l6KS8Sa3JDTuH#invoice-entity</a></p></td></tr><tr><td>receipt</td><td>false</td><td>object</td><td><p>Used for present receipt for the consumer after the payment</p><p>See receipt object entity: <a data-mention href="/pages/WKTUNOCqigLdZVBDQky6#receipt-entity">/pages/WKTUNOCqigLdZVBDQky6#receipt-entity</a></p></td></tr><tr><td>emailConfig.paymentRequest.language</td><td>false</td><td>string</td><td>[ en, he, ru ]</td></tr><tr><td>receiptNotifications</td><td>false</td><td>object</td><td><p>Receipt Notifications</p><p>entity: <a href="/pages/nJPI2KiZhlIdNLHVbLhs">Receipt Notifications</a></p></td></tr><tr><td>products</td><td>false</td><td>object</td><td><p>Products information</p><p>See product object entity: <a data-mention href="/pages/RXt5EFpXbQJY305RhjWI#product-model">/pages/RXt5EFpXbQJY305RhjWI#product-model</a></p></td></tr><tr><td>metadata</td><td>false</td><td>object</td><td>a unique array with a key-value pair for displaying information on SensePass Dashboard (backoffice) <a data-mention href="/pages/H11U7C3bpfjfji23uy2J">/pages/H11U7C3bpfjfji23uy2J</a></td></tr><tr><td>billingAddress</td><td>false</td><td>object</td><td>Customer's billing address entity: <a href="/pages/2Nuf0KxR2prFiP7jDQaZ">Customer Billing Details Model</a></td></tr><tr><td>shippingAddress</td><td>false</td><td>object</td><td>Customer's shipping address entity: <a href="/pages/2Nuf0KxR2prFiP7jDQaZ">Customer Shipping Details Model</a></td></tr><tr><td>paymentDetails</td><td>false</td><td>object</td><td><p>Payment details Input</p><p>entity: <a href="/pages/meG3ICQ4kE8v3AFNp5Ra">Payment Details Model</a></p></td></tr><tr><td>hideAmount</td><td>false</td><td>boolean</td><td>Determines whether the transaction amount is displayed on the payment page or not</td></tr><tr><td>additionalData</td><td>false</td><td>object</td><td>Any additional data that may be sent to the processor <a data-mention href="/pages/oYHABSVKAqHXXgy5c8Vg">/pages/oYHABSVKAqHXXgy5c8Vg</a></td></tr><tr><td>approvalMessage</td><td>false</td><td>string</td><td>Message to appear in the header of confirmation page</td></tr><tr><td>authorizationText</td><td>false</td><td>string</td><td><p>Message to appear on tokenized transactions . default value is: </p><pre><code>I authorize {{businessName}} to process future payments
</code></pre></td></tr><tr><td>orderId</td><td>false</td><td>string</td><td>Order ID you can send which will be shown on the payment request/invoice emails (according to Merchant/Location Settings).</td></tr><tr><td>invoiceId</td><td>false</td><td>string</td><td>Invoice ID you can send which will be shown on the payment request/invoice emails (according to Merchant/Location Settings).</td></tr><tr><td>level</td><td>false</td><td>object</td><td>Payment method Level 2 or 3 requirements: <a data-mention href="/pages/ypmYaLXkdLSRdNR2wkWZ">/pages/ypmYaLXkdLSRdNR2wkWZ</a></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK OK" %}
**See Transactions entity schema:** [Transaction Model](/sensepay/transaction-api/models/transaction-model.md#transaction-entity)

```javascript
{
  "TransactionNumber": "14a4334a32c852aeb0cfae52cbff1314649da7f175a8e140b35c147c",
  "date": "2019-12-19T09:47:59.105Z",
  "amount": "1234.56",
  "currency": "USD",
  "status": 0,
  "statusName": "Transaction Approved",
  "pos": "POS 3, Branch Tel Aviv",
  "posReceiptsEndpoint": "http://pay.sensepass-api.com/api/invoicesReceipts/receipt/save/hofai3478o8o78o4s849j3920ckj",
  "posData": {
    "foo": "bar",
    "hello": [
      "world"
    ]
  },
  "businessName": "Coffee Bar",
  "businessId": 144,
  "timeoutDate": "2019-12-19T09:47:59.105Z",
  "paymentMethodData": {
    "PaymentType": "Bit",
    "directAppLinks": {
      "iOSLink": "paymentsBIT://www.bitpay.co.il/app/bitcom-info",
      "androidLink": "intent://www.bitpay.co.il/app/bitcom-info;scheme=bit;package=com.bnhp.payments.paymentsapp;end",
      "qrURL": "https://www.bitpay.co.il/app/bitcom-info"
    }
  },
  "SMS": "Sent",
  "paymentCommit": {
    "messsage": "Payment commit is enabled for this transaction",
    "isPaymentCommitted": false,
    "secondsToCommit": 60,
    "commitLink": "https://pay.sensepass-api.com/api/transactions/commitPayment/ec2dc489d161aa27a803f48bcf5ffcf"
  },
  "products": [
    {
      "name": "Coffee",
      "quantity": 2,
      "amount": 100,
      "discount": 0,
      "posIdentifier": "1234A"
    },
    {
      "name": "Beer",
      "quantity": 1,
      "amount": 600,
      "discount": 0,
      "posIdentifier": "1234B"
    }
  ],
  "productSumMismatch": true,
  "confirmations": [
    {
      "paymentType": "Regular",
      "confirmationNumber": "063-d9j09YsY1",
      "fullConfirmationCode": "063-d9j09YsY1",
      "dateApproval": "2019-12-19T09:47:59.105Z",
      "installments": 1,
      "paymentMethodName": "PayPal",
      "approvedBy": "PayPal",
      "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
      "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
      "authNumber": "123213dsf13111",
      "referenceNumber": "1778298289",
      "acquirer": "Visa",
      "voucher": "yyyAbnlmlfm1323",
      "lastFourDigits": "8858",
      "sensePassReferenceId": "34e209ea8b24cc831cf"
    }
  ],
  "confirmation": {
    "paymentType": "Regular",
    "confirmationNumber": "063-d9j09YsY1",
    "fullConfirmationCode": "063-d9j09YsY1",
    "dateApproval": "2019-12-19T09:47:59.105Z",
    "installments": 1,
    "paymentMethodName": "PayPal",
    "approvedBy": "PayPal",
    "providerId": "uGfNuwEGiP18SUnTUEo1/atTdesDnhDhZ/8i7G9NAEg=",
    "requestID": "a4dbf66e-d3f1-4a29-baf7-2591424a9a0c",
    "authNumber": "123213dsf13111",
    "referenceNumber": "1778298289",
    "acquirer": "Visa",
    "voucher": "yyyAbnlmlfm1323",
    "lastFourDigits": "8858",
    "sensePassReferenceId": "34e209ea8b24cc831cf"
  },
  "transactionPage": {
    "iOSLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "androidLink": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "qrURL": "https://mbeta.sensepass-api.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
    "consumerPage": {
            "regular": "https://pay.sandbox.sensepass.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872",
            "medium": "https://pay.sandbox.sensepass.com/orderSummary/027e4e48d59fdbe83f5a78cab62a53c676b7f111fa9d0ee0a36d1872?viewMode=medium"
        }
  },
  "balance": 0
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid Input" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Error" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### Examples

Basic request example to create a new transaction.

```json
{
  "timeOut": 600,
  "amount": 200,
  "isCent": true,
  "currency": "USD",
  "deviceId": "2ooeww5ufzg3nkuf8a10gu5n695yolixlbgb042o03to9bxfkr7t815i5epu8o58jv1rznif3o1tr6xsb1rm"
}

```

See our full examples for creating transactions on the left menu.

### Schema

Full Transaction Entity schema: [Transaction Model](/sensepay/transaction-api/models/transaction-model.md#transaction-entity)

### Flow Chart

[See our payment flow chart here](/sensepay/transaction-api/flow-charts/payment-flow.md)

### Transaction Status Flow

[See our transaction status flow here](/sensepay/transaction-api/flow-charts/transaction-status-flow.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sensepass.com/sensepay/transaction-api/payment-flows/create-a-transaction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.