# Create a transaction

API for creating new payment requests, this API create [Transaction Entity](https://docs.sensepass.com/sensepay/transaction-api/models/transaction-model).

### 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](https://docs.sensepass.com/sensepay/transaction-api/authentication)

#### 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="../../models/transaction-model#transaction-entity">#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="../../models/invoice-model#invoice-entity">#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="../../models/receipts-model#receipt-entity">#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="../models/receipt-notifications-model">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="../../models/product-model#product-model">#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="../models/metadata-model">metadata-model</a></td></tr><tr><td>billingAddress</td><td>false</td><td>object</td><td>Customer's billing address entity: <a href="../models/customer-shipping-billing-details-model">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="../models/customer-shipping-billing-details-model">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="../models/payment-details-model">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="../models/additional-data-model">additional-data-model</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="../models/payment-method-level-model">payment-method-level-model</a></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK OK" %}
**See Transactions entity schema:** [#transaction-entity](https://docs.sensepass.com/sensepay/models/transaction-model#transaction-entity "mention")

```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-entity](https://docs.sensepass.com/sensepay/models/transaction-model#transaction-entity "mention")

### Flow Chart

[See our payment flow chart here](https://docs.sensepass.com/sensepay/transaction-api/flow-charts/payment-flow)

### Transaction Status Flow

[See our transaction status flow here](https://docs.sensepass.com/sensepay/transaction-api/flow-charts/transaction-status-flow)