{
  "info": {
    "name": "Shukria Payments — MPGS API: Retrieve Transaction",
    "description": "Retrieve a single transaction on an MPGS order — a payment, capture, refund, void or any other transaction recorded against it. Works for every MPGS flow (Hosted Checkout, Hosted Session, Direct).\n\nSet the collection variables before sending:\n- `merchant_api_key`: the merchant's API key (starts with `shkdirect_`).\n- `order_ref`: CloudLayer's order id (`pg_transactions.gateway_order_ref`, also returned as `reference` by `/pay/status`).\n- `txn_id`: the payment transaction on that order (`pg_transactions.pg_reference`; the `transaction_id` in the payment result).\n- `refund_txn_id`: a refund id sent with the Refund API on `order_ref`.\n- `void_order_ref` / `void_txn_id`: an order and the void id sent with the Void API.\n\nVoid and refund transaction ids are the `{transactionid}` the merchant chose when making them.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{merchant_api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://mercurypay.ariticapp.com/pn"
    },
    {
      "key": "pg_prefix",
      "value": "/pgpayments"
    },
    {
      "key": "merchant_api_key",
      "value": "YOUR_MERCHANT_API_KEY"
    },
    {
      "key": "order_ref",
      "value": "945"
    },
    {
      "key": "txn_id",
      "value": "1"
    },
    {
      "key": "refund_txn_id",
      "value": "PASTE_A_REFUND_ID"
    },
    {
      "key": "void_order_ref",
      "value": "914"
    },
    {
      "key": "void_txn_id",
      "value": "void-914-1"
    }
  ],
  "item": [
    {
      "name": "1 · Retrieve payment transaction",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const body = pm.response.json();",
              "pm.test('HTTP 200', () => pm.response.to.have.status(200));",
              "pm.test('result is not ERROR', () => pm.expect(body.result).to.be.oneOf(['SUCCESS', 'FAILURE', 'PENDING', 'UNKNOWN']));",
              "pm.test('merchant present', () => pm.expect(body.merchant).to.be.a('string'));",
              "pm.test('order fields present', () => {",
              "  ['amount', 'creationTime', 'currency', 'id', 'lastUpdatedTime', 'merchantAmount', 'merchantCurrency',",
              "   'totalAuthorizedAmount', 'totalCapturedAmount', 'totalDisbursedAmount', 'totalRefundedAmount']",
              "    .forEach(f => pm.expect(body.order).to.have.property(f));",
              "});",
              "pm.test('order.id matches', () => pm.expect(body.order.id).to.eql(pm.variables.get('order_ref')));",
              "pm.test('response.gatewayCode present', () => pm.expect(body.response.gatewayCode).to.be.a('string'));",
              "pm.test('transaction fields present', () => {",
              "  ['amount', 'currency', 'id', 'type', 'acquirer'].forEach(f => pm.expect(body.transaction).to.have.property(f));",
              "});",
              "pm.test('transaction.id matches', () => pm.expect(body.transaction.id).to.eql(pm.variables.get('txn_id')));",
              "pm.test('transaction.type is PAYMENT or AUTHORIZATION', () =>",
              "  pm.expect(body.transaction.type).to.be.oneOf(['PAYMENT', 'AUTHORIZATION']));"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{order_ref}}/transaction/{{txn_id}}",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{order_ref}}",
            "transaction",
            "{{txn_id}}"
          ]
        },
        "description": "Retrieves the order's payment transaction. `txn_id` is `pg_transactions.pg_reference` for the order — the `transaction_id` in the merchant's payment result (e.g. `1` for Hosted Checkout, `<order>-1` or `<order>-1-pay` for Hosted Session / Direct).\n\nSuccess returns: merchant, result, order {amount, creationTime, currency, id, lastUpdatedTime, merchantAmount, merchantCurrency, totalAuthorizedAmount, totalCapturedAmount, totalDisbursedAmount, totalRefundedAmount}, response {gatewayCode}, transaction {acquirer {id}, amount, currency, id, type}.\n\nA declined transaction is still HTTP 200, with `result: FAILURE`."
      },
      "response": []
    },
    {
      "name": "2 · Retrieve refund transaction",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const body = pm.response.json();",
              "pm.test('HTTP 200', () => pm.response.to.have.status(200));",
              "pm.test('result is not ERROR', () => pm.expect(body.result).to.be.oneOf(['SUCCESS', 'FAILURE', 'PENDING', 'UNKNOWN']));",
              "pm.test('merchant present', () => pm.expect(body.merchant).to.be.a('string'));",
              "pm.test('order fields present', () => {",
              "  ['amount', 'creationTime', 'currency', 'id', 'lastUpdatedTime', 'merchantAmount', 'merchantCurrency',",
              "   'totalAuthorizedAmount', 'totalCapturedAmount', 'totalDisbursedAmount', 'totalRefundedAmount']",
              "    .forEach(f => pm.expect(body.order).to.have.property(f));",
              "});",
              "pm.test('order.id matches', () => pm.expect(body.order.id).to.eql(pm.variables.get('order_ref')));",
              "pm.test('response.gatewayCode present', () => pm.expect(body.response.gatewayCode).to.be.a('string'));",
              "pm.test('transaction fields present', () => {",
              "  ['amount', 'currency', 'id', 'type', 'acquirer'].forEach(f => pm.expect(body.transaction).to.have.property(f));",
              "});",
              "pm.test('transaction.id matches', () => pm.expect(body.transaction.id).to.eql(pm.variables.get('refund_txn_id')));",
              "pm.test('transaction.type is REFUND', () => pm.expect(body.transaction.type).to.eql('REFUND'));"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{order_ref}}/transaction/{{refund_txn_id}}",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{order_ref}}",
            "transaction",
            "{{refund_txn_id}}"
          ]
        },
        "description": "Retrieves a refund made through the Refund API. Set `refund_txn_id` to a refund id from a Refund collection run on `order_ref` (it is the `{transactionid}` that refund was sent with)."
      },
      "response": []
    },
    {
      "name": "3 · Retrieve void transaction",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const body = pm.response.json();",
              "pm.test('HTTP 200', () => pm.response.to.have.status(200));",
              "pm.test('result is not ERROR', () => pm.expect(body.result).to.be.oneOf(['SUCCESS', 'FAILURE', 'PENDING', 'UNKNOWN']));",
              "pm.test('merchant present', () => pm.expect(body.merchant).to.be.a('string'));",
              "pm.test('order fields present', () => {",
              "  ['amount', 'creationTime', 'currency', 'id', 'lastUpdatedTime', 'merchantAmount', 'merchantCurrency',",
              "   'totalAuthorizedAmount', 'totalCapturedAmount', 'totalDisbursedAmount', 'totalRefundedAmount']",
              "    .forEach(f => pm.expect(body.order).to.have.property(f));",
              "});",
              "pm.test('order.id matches', () => pm.expect(body.order.id).to.eql(pm.variables.get('void_order_ref')));",
              "pm.test('response.gatewayCode present', () => pm.expect(body.response.gatewayCode).to.be.a('string'));",
              "pm.test('transaction fields present', () => {",
              "  ['amount', 'currency', 'id', 'type', 'acquirer'].forEach(f => pm.expect(body.transaction).to.have.property(f));",
              "});",
              "pm.test('transaction.id matches', () => pm.expect(body.transaction.id).to.eql(pm.variables.get('void_txn_id')));",
              "pm.test('transaction.type is a VOID_* type', () => pm.expect(body.transaction.type).to.match(/^VOID_/));"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{void_order_ref}}/transaction/{{void_txn_id}}",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{void_order_ref}}",
            "transaction",
            "{{void_txn_id}}"
          ]
        },
        "description": "Retrieves a void made through the Void API. `void_order_ref` / `void_txn_id` are the order and the `{transactionid}` the void was sent with."
      },
      "response": []
    },
    {
      "name": "4 · Unknown transaction id (expect ERROR)",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const body = pm.response.json();",
              "pm.test('not a server error', () => pm.expect(pm.response.code).to.be.below(500));",
              "pm.test('result is ERROR', () => pm.expect(body.result).to.eql('ERROR'));",
              "pm.test('error.cause present', () => pm.expect(body.error).to.have.property('cause'));"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{order_ref}}/transaction/does-not-exist",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{order_ref}}",
            "transaction",
            "does-not-exist"
          ]
        },
        "description": "A transaction id that does not exist on the order. MPGS rejects it; CloudLayer passes its error through — never a 5xx."
      },
      "response": []
    },
    {
      "name": "5 · Transaction id over 40 characters (expect 400)",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "const body = pm.response.json();",
              "pm.test('HTTP 400', () => pm.response.to.have.status(400));",
              "pm.test('result is ERROR', () => pm.expect(body.result).to.eql('ERROR'));",
              "pm.test('cause is INVALID_REQUEST', () => pm.expect(body.error.cause).to.eql('INVALID_REQUEST'));",
              "pm.test('field is transactionid', () => pm.expect(body.error.field).to.eql('transactionid'));",
              "pm.test('validationType is INVALID', () => pm.expect(body.error.validationType).to.eql('INVALID'));"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{order_ref}}/transaction/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{order_ref}}",
            "transaction",
            "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ]
        },
        "description": "MPGS limits transaction ids to 40 characters. Rejected by CloudLayer before MPGS is called."
      },
      "response": []
    },
    {
      "name": "6 · Bad API key (expect 401)",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test('HTTP 401', () => pm.response.to.have.status(401));",
              "pm.test('error is unauthorized', () => pm.expect(pm.response.json().error).to.eql('unauthorized'));"
            ]
          }
        }
      ],
      "request": {
        "auth": {
          "type": "bearer",
          "bearer": [
            {
              "key": "token",
              "value": "shkdirect_invalid",
              "type": "string"
            }
          ]
        },
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": {
          "raw": "{{base_url}}{{pg_prefix}}/api/mpgs/order/{{order_ref}}/transaction/{{txn_id}}",
          "host": [
            "{{base_url}}{{pg_prefix}}"
          ],
          "path": [
            "api",
            "mpgs",
            "order",
            "{{order_ref}}",
            "transaction",
            "{{txn_id}}"
          ]
        },
        "description": "Rejected by MerchantApiAuthPlug."
      },
      "response": []
    }
  ]
}