# Transaction Workflow Tutorial
source: https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/adoptions-tutorial/index.md

👉 Replace the generic transaction flow, encrypted routes, payloads, and identifiers in this tutorial with the real downstream workflow your service supports. Remove any steps that do not apply to your API.

## Overview {#overview}

Use this tutorial to test the transaction endpoints in the {Your Service Name} service, including transaction creation, follow-up actions, retrieval, updates, and deletion.

### Prerequisites {#prerequisites}

* A project created for your service on Mastercard Developers.
* Sandbox credentials and downloaded keys stored safely.
* A configured API client such as Postman or Insomnia.
* Authentication configured before you send requests.

Example client configuration:

```json
{
  "scheme": "https",
  "base_path": "",
  "host": "sandbox.api.mastercard.com",
  "mastercard": {
    "consumerKey": "{your consumerKey}",
    "keyAlias": "{your keyAlias}",
    "keystoreP12Path": "/path/to/your/file",
    "keystorePassword": "{your keystorePassword}"
  }
}
```

<br />

* Payload encryption is required for transaction endpoints that carry sensitive customer or account data.

```text
POST /transactions
POST /transactions/{transaction_id}/actions
PUT /transactions/{transaction_id}
```

### What You Will Learn {#what-you-will-learn}

* How to create, action, retrieve, search, update, and delete transaction records

## Transactions {#transactions}

### Post a transaction {#post-a-transaction}

1. To log a transaction, use the resource identifier you received when you created the related primary resource.
2. Include the required owner or actor information for the workflow.
3. If the route requires encryption, configure the body encryption before sending the request.

   ```json
   {
     "path": "/transactions",
     "toEncrypt": [
       {
         "element": "owner",
         "obj": "encryptedOwner"
       }
     ],
     "toDecrypt": [
       {
         "element": "encryptedOwner",
         "obj": "owner"
       }
     ]
   }
   ```

```yaml
POST https://sandbox.api.mastercard.com/{your-service}/transactions
```

```json
{
  "resourceId": "12345678-1234-1234-1234-123456789abc",
  "owner": {
    "firstName": "Alex",
    "lastName": "Jordan",
    "phoneNumber": "+15555550100",
    "reference": "ABC-123"
  }
}
```

### Post the follow-up transaction action {#post-the-follow-up-transaction-action}

1. After you receive a success response, capture the `transaction_id` from the response body or `Location` header.
2. Use this value as a parameter to complete the next step in the workflow.
3. If the route requires encryption, configure full-body encryption before sending the request.

   ```json
   {
     "path": "/actions",
     "toEncrypt": [
       {
         "element": "$",
         "obj": "$"
       }
     ],
     "toDecrypt": [
       {
         "element": "$",
         "obj": "$"
       }
     ]
   }
   ```

```yaml
POST https://sandbox.api.mastercard.com/{your-service}/transactions/{transaction_id}/actions
```

```json
{
  "amount": 49.99,
  "currency": "EUR",
  "source": {
    "name": "John Doe",
    "reference": "PAYMENT-123"
  }
}
```

### Get historical transactions {#get-historical-transactions}

1. You can fetch transaction records with query parameters such as `from_date`, `to_date`, `category`, and the related resource identifier.

```yaml
GET https://sandbox.api.mastercard.com/{your-service}/transactions?from_date=2024-01-01&to_date=2026-01-01&resource_id=12345678-1234-1234-1234-123456789abc
```

### Get a single transaction record {#get-a-single-transaction-record}

1. You can also use the `transaction_id` as a parameter to retrieve a single transaction record.

```yaml
GET https://sandbox.api.mastercard.com/{your-service}/transactions/{transaction_id}
```

### Update a transaction {#update-a-transaction}

1. The `transaction_id`, along with an `If-Match` header, are required to update a transaction record.
2. If the route requires encryption, configure the payload before sending the request.

   ```json
   {
     "path": "/transactions",
     "toEncrypt": [
       {
         "element": "transaction",
         "obj": "$"
       }
     ],
     "toDecrypt": [
       {
         "element": "$.encryptedTransaction",
         "obj": "$"
       }
     ]
   }
   ```

```yaml
PUT https://sandbox.api.mastercard.com/{your-service}/transactions/{transaction_id}
```

`If-Match (header)`: `0`

```json
{
  "transaction": {
    "id": "76543210-4321-4321-4321-cba987654321",
    "resourceId": "12345678-1234-1234-1234-123456789abc",
    "transactionDate": "2026-04-07",
    "owner": {
      "firstName": "Alex",
      "lastName": "Jordan",
      "phoneNumber": "+15555550100",
      "reference": "ABC-123"
    }
  }
}
```

### Delete a transaction {#delete-a-transaction}

1. To remove a transaction, use the `transaction_id` as a parameter in a `DELETE` request.

```yaml
DELETE https://sandbox.api.mastercard.com/{your-service}/transactions/{transaction_id}
```