Omise Postman Collection

The official Omise Postman collection provides a comprehensive set of pre-configured API requests for testing, development, and automation. With over 100+ endpoints organized by resource type, you can quickly test Omise APIs, debug integration issues, and automate testing workflows.

Overview

What is Postman?

Postman is a popular API development platform that simplifies the process of building, testing, and documenting APIs. It provides:

Interactive Request Builder - Construct API requests with a user-friendly interface
Collection Management - Organize related requests into collections
Environment Variables - Manage different configurations (test, production)
Automated Testing - Write tests and run them automatically
Team Collaboration - Share collections with team members
CI/CD Integration - Integrate API tests into deployment pipelines

Why Use the Omise Collection?

The Omise Postman collection offers:

Pre-configured Requests - 100+ ready-to-use API endpoints
Example Responses - Real API response samples for each endpoint
Authentication Setup - Automatic API key handling
Environment Templates - Test and production configurations
Request Validation - Pre-written tests for common scenarios
Workflow Examples - Multi-step payment scenarios
Documentation - Inline documentation for each request

Installation

Prerequisites

Postman Account - Free account at postman.com
Omise Account - Active account with API keys
Postman App - Desktop app or web version

Importing the Collection

Method 1: Direct Import from URL

Open Postman
Click Import Button

Located in the top-left corner of the Postman app
Select "Link" Tab

Enter Collection URL

https://www.postman.com/omise-api/workspace/omise-public/collection/12345678-abcd-1234-efgh-1234567890ab

Click Continue and Import

Method 2: Import from File

Download Collection

Visit the Omise Postman workspace and download the collection JSON file
Import to Postman
- Click Import button
- Select "File" tab
- Choose downloaded JSON file
- Click Import

Method 3: Fork from Workspace

Visit Omise Public Workspace

Go to Omise Postman Workspace
Fork Collection

Click "Fork" button on the collection
Create Fork

Select your workspace and click "Fork Collection"

Verifying Installation

After importing, you should see:

Omise API Collection in your Collections sidebar
Organized Folders for each resource type (Charges, Customers, etc.)
Environment Templates in your Environments section

Setting Up Environment Variables

Environment variables allow you to switch between test and production environments easily.

Creating Test Environment

Click Environments Icon

Located in the left sidebar
Click "+" to Create New Environment
Name the Environment

Enter "Omise Test"
Add Variables

Variable Type Value
base_url default https://api.omise.co
secret_key secret skey_test_your_secret_key
public_key default pkey_test_your_public_key
api_version default 2019-05-29
Save Environment

Variable	Type	Value
`base_url`	default	`https://api.omise.co`
`secret_key`	secret	`skey_test_your_secret_key`
`public_key`	default	`pkey_test_your_public_key`
`api_version`	default	`2019-05-29`

Creating Production Environment

Repeat the process for production:

Create New Environment - Name it "Omise Production"
Add Variables with live keys:

Variable Type Value
base_url default https://api.omise.co
secret_key secret skey_live_your_secret_key
public_key default pkey_live_your_public_key
api_version default 2019-05-29
Save Environment

Variable	Type	Value
`base_url`	default	`https://api.omise.co`
`secret_key`	secret	`skey_live_your_secret_key`
`public_key`	default	`pkey_live_your_public_key`
`api_version`	default	`2019-05-29`

Using Environment Variables in Requests

Variables are automatically used in collection requests:

{{base_url}}/charges
Authorization: Basic {{secret_key}}

Selecting Active Environment

Choose the environment from the dropdown in the top-right corner:

Select "Omise Test" for development
Select "Omise Production" for production testing (use with caution)

Authentication Configuration

The Omise Postman collection uses HTTP Basic Authentication with your API keys.

How Authentication Works

Omise uses your secret key as the username with an empty password:

Username: skey_test_your_secret_key
Password: (empty)

Configuring Authentication

Authentication is pre-configured in the collection, but you can customize it:

Open Collection Settings

Click the "..." menu next to the collection name
Select "Edit"
Go to "Authorization" Tab
Verify Settings
- Type: Basic Auth
- Username: {{secret_key}}
- Password: (empty)
Save Changes

Testing Authentication

Verify authentication is working:

Select "Get Balance" Request

Found in the "Balance" folder
Send Request
Check Response
- Status: 200 OK
- Body contains your account balance

If authentication fails:

Verify API key is correct
Check environment is selected
Ensure no extra spaces in key

Available Endpoints

The Omise Postman collection includes all API endpoints organized by resource type.

Charges

Folder: Charges

Endpoint	Method	Description
List Charges	GET	Retrieve paginated list of charges
Create Charge	POST	Create a new charge
Get Charge	GET	Retrieve specific charge by ID
Update Charge	PATCH	Update charge metadata
Capture Charge	POST	Capture authorized charge
Reverse Charge	POST	Reverse uncaptured charge
List Charge Schedules	GET	List scheduled charges
Expire Charge	POST	Expire pending charge

Example Variables:

{{charge_id}} - Charge ID (e.g., chrg_test_5v7h8gp2xqf0v0k4zy7)

Customers

Folder: Customers

Endpoint	Method	Description
List Customers	GET	Get all customers
Create Customer	POST	Create new customer
Get Customer	GET	Retrieve customer details
Update Customer	PATCH	Update customer information
Delete Customer	DELETE	Delete customer

Example Variables:

{{customer_id}} - Customer ID (e.g., cust_test_5v7h8gp2xqf0v0k4zy7)

Cards

Folder: Cards

Endpoint	Method	Description
List Cards	GET	List customer cards
Get Card	GET	Get card details
Update Card	PATCH	Update card information
Delete Card	DELETE	Remove card

Example Variables:

{{card_id}} - Card ID (e.g., card_test_5v7h8gp2xqf0v0k4zy7)

Tokens

Folder: Tokens

Endpoint	Method	Description
Create Token	POST	Tokenize card information
Get Token	GET	Retrieve token details

Example Variables:

{{token_id}} - Token ID (e.g., tokn_test_5v7h8gp2xqf0v0k4zy7)

Refunds

Folder: Refunds

Endpoint	Method	Description
List Refunds	GET	List all refunds for a charge
Create Refund	POST	Issue full or partial refund
Get Refund	GET	Get refund details

Example Variables:

{{refund_id}} - Refund ID (e.g., rfnd_test_5v7h8gp2xqf0v0k4zy7)

Transfers

Folder: Transfers

Endpoint	Method	Description
List Transfers	GET	List all transfers
Create Transfer	POST	Create manual transfer
Get Transfer	GET	Get transfer details
Update Transfer	PATCH	Update transfer information
Destroy Transfer	DELETE	Cancel scheduled transfer
List Transfer Schedules	GET	List scheduled transfers

Example Variables:

{{transfer_id}} - Transfer ID (e.g., trsf_test_5v7h8gp2xqf0v0k4zy7)

Recipients

Folder: Recipients

Endpoint	Method	Description
List Recipients	GET	List all recipients
Create Recipient	POST	Create new recipient
Get Recipient	GET	Get recipient details
Update Recipient	PATCH	Update recipient information
Delete Recipient	DELETE	Delete recipient

Example Variables:

{{recipient_id}} - Recipient ID (e.g., recp_test_5v7h8gp2xqf0v0k4zy7)

Disputes

Folder: Disputes

Endpoint	Method	Description
List Disputes	GET	List all disputes
Get Dispute	GET	Get dispute details
Update Dispute	PATCH	Update dispute information
List Dispute Documents	GET	List dispute documents
Upload Dispute Document	POST	Upload dispute evidence

Example Variables:

{{dispute_id}} - Dispute ID (e.g., dspt_test_5v7h8gp2xqf0v0k4zy7)

Sources

Folder: Sources

Endpoint	Method	Description
Create Source	POST	Create payment source
Get Source	GET	Get source details

Example Variables:

{{source_id}} - Source ID (e.g., src_test_5v7h8gp2xqf0v0k4zy7)

Balance

Folder: Balance

Endpoint	Method	Description
Get Balance	GET	Retrieve account balance

Transactions

Folder: Transactions

Endpoint	Method	Description
List Transactions	GET	List all transactions
Get Transaction	GET	Get transaction details

Example Variables:

{{transaction_id}} - Transaction ID (e.g., trxn_test_5v7h8gp2xqf0v0k4zy7)

Events

Folder: Events

Endpoint	Method	Description
List Events	GET	List all events
Get Event	GET	Get event details

Example Variables:

{{event_id}} - Event ID (e.g., evnt_test_5v7h8gp2xqf0v0k4zy7)

Webhooks

Folder: Webhooks

Endpoint	Method	Description
List Webhooks	GET	List webhook endpoints
Create Webhook	POST	Create webhook endpoint
Get Webhook	GET	Get webhook details
Update Webhook	PATCH	Update webhook
Delete Webhook	DELETE	Delete webhook

Example Variables:

{{webhook_id}} - Webhook ID (e.g., whev_test_5v7h8gp2xqf0v0k4zy7)

Links

Folder: Payment Links

Endpoint	Method	Description
List Links	GET	List payment links
Create Link	POST	Create payment link
Get Link	GET	Get link details

Example Variables:

{{link_id}} - Link ID (e.g., link_test_5v7h8gp2xqf0v0k4zy7)

Capabilities

Folder: Capabilities

Endpoint	Method	Description
Get Capabilities	GET	Get account capabilities

Chains

Folder: Charge Schedules

Endpoint	Method	Description
List Chains	GET	List charge schedules
Get Chain	GET	Get schedule details

Example Variables:

{{chain_id}} - Chain ID (e.g., sch_test_5v7h8gp2xqf0v0k4zy7)

Example Requests

Creating a Charge

Request:

POST {{base_url}}/charges
Authorization: Basic {{secret_key}}
Content-Type: application/json

{
  "amount": 100000,
  "currency": "THB",
  "card": "tokn_test_5v7h8gp2xqf0v0k4zy7",
  "description": "Test charge from Postman",
  "metadata": {
    "order_id": "ORDER-12345",
    "customer_name": "John Doe"
  }
}

Response:

{
  "object": "charge",
  "id": "chrg_test_5v7h8gp2xqf0v0k4zy7",
  "amount": 100000,
  "currency": "THB",
  "status": "successful",
  "paid": true,
  "description": "Test charge from Postman",
  "metadata": {
    "order_id": "ORDER-12345",
    "customer_name": "John Doe"
  }
}

Creating a Customer

Request:

POST {{base_url}}/customers
Authorization: Basic {{secret_key}}
Content-Type: application/json

{
  "email": "customer@example.com",
  "description": "VIP Customer",
  "card": "tokn_test_5v7h8gp2xqf0v0k4zy7",
  "metadata": {
    "tier": "premium",
    "signup_date": "2026-01-15"
  }
}

Response:

{
  "object": "customer",
  "id": "cust_test_5v7h8gp2xqf0v0k4zy7",
  "email": "customer@example.com",
  "description": "VIP Customer",
  "default_card": "card_test_5v7h8gp2xqf0v0k4zy7",
  "metadata": {
    "tier": "premium",
    "signup_date": "2026-01-15"
  }
}

Creating a Refund

Request:

POST {{base_url}}/charges/{{charge_id}}/refunds
Authorization: Basic {{secret_key}}
Content-Type: application/json

{
  "amount": 50000,
  "metadata": {
    "reason": "Customer request",
    "refund_type": "partial"
  }
}

Response:

{
  "object": "refund",
  "id": "rfnd_test_5v7h8gp2xqf0v0k4zy7",
  "amount": 50000,
  "currency": "THB",
  "charge": "chrg_test_5v7h8gp2xqf0v0k4zy7",
  "transaction": "trxn_test_5v7h8gp2xqf0v0k4zy7",
  "metadata": {
    "reason": "Customer request",
    "refund_type": "partial"
  }
}

Creating a Token

Request:

POST {{base_url}}/tokens
Authorization: Basic {{public_key}}
Content-Type: application/json

{
  "card": {
    "name": "John Doe",
    "number": "4242424242424242",
    "expiration_month": 12,
    "expiration_year": 2027,
    "security_code": "123"
  }
}

Response:

{
  "object": "token",
  "id": "tokn_test_5v7h8gp2xqf0v0k4zy7",
  "used": false,
  "card": {
    "object": "card",
    "name": "John Doe",
    "last_digits": "4242",
    "brand": "Visa",
    "expiration_month": 12,
    "expiration_year": 2027
  }
}

Testing Workflows

The Omise Postman collection includes pre-built workflow examples for common payment scenarios.

Workflow 1: Complete Payment Flow

This workflow demonstrates creating a charge and verifying the result:

Create Token

Tokenize card information
Create Charge

Use token to create charge
Get Charge

Verify charge was successful
List Transactions

View transaction history

Running the Workflow:

Open the "Workflows" folder
Select "Complete Payment Flow"
Click "Run" button
View results in Collection Runner

Workflow 2: Customer Management

Create a customer with a card and charge them:

Create Token

Tokenize card
Create Customer

Create customer with token
Create Charge with Customer

Charge the customer
Get Customer

Verify customer details

Workflow 3: Refund Process

Handle refunds properly:

Get Charge

Retrieve charge to refund
Create Refund

Issue full or partial refund
Get Refund

Verify refund status
Get Charge Again

Verify charge reflects refund

Workflow 4: 3D Secure Payment

Test 3D Secure authentication:

Create Source

Create 3DS source
Create Charge

Create charge with source
Get Source

Get authorization URL
Complete Authentication

User completes 3DS
Verify Charge

Confirm charge succeeded

CI/CD Integration

Integrate Omise API tests into your CI/CD pipeline using Newman, Postman's command-line collection runner.

Installing Newman

Install Newman globally:

npm install -g newman

Or add to your project:

npm install --save-dev newman

Exporting Collection and Environment

Export Collection
- Open collection menu
- Click "Export"
- Choose "Collection v2.1"
- Save as omise-collection.json
Export Environment
- Open environment menu
- Click "..." next to environment
- Select "Export"
- Save as omise-test-env.json

Running Tests with Newman

Basic command:

newman run omise-collection.json \
  --environment omise-test-env.json \
  --reporters cli,json

GitHub Actions Integration

Create .github/workflows/api-tests.yml:

name: API Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    
    - name: Install Newman
      run: npm install -g newman newman-reporter-htmlextra
    
    - name: Create environment file
      run: |
        cat > omise-test-env.json << EOF
        {
          "name": "Omise Test",
          "values": [
            {
              "key": "base_url",
              "value": "https://api.omise.co",
              "enabled": true
            },
            {
              "key": "secret_key",
              "value": "${{ secrets.OMISE_SECRET_KEY }}",
              "enabled": true
            },
            {
              "key": "public_key",
              "value": "${{ secrets.OMISE_PUBLIC_KEY }}",
              "enabled": true
            }
          ]
        }
        EOF
    
    - name: Run API tests
      run: |
        newman run tests/omise-collection.json \
          --environment omise-test-env.json \
          --reporters cli,htmlextra \
          --reporter-htmlextra-export reports/api-tests.html
    
    - name: Upload test results
      if: always()
      uses: actions/upload-artifact@v3
      with:
        name: test-results
        path: reports/

GitLab CI Integration

Create .gitlab-ci.yml:

api_tests:
  image: node:18
  stage: test
  before_script:
    - npm install -g newman
  script:
    - |
      cat > omise-test-env.json << EOF
      {
        "name": "Omise Test",
        "values": [
          {
            "key": "base_url",
            "value": "https://api.omise.co"
          },
          {
            "key": "secret_key",
            "value": "${OMISE_SECRET_KEY}"
          },
          {
            "key": "public_key",
            "value": "${OMISE_PUBLIC_KEY}"
          }
        ]
      }
      EOF
    - newman run tests/omise-collection.json \
        --environment omise-test-env.json \
        --reporters cli,junit \
        --reporter-junit-export reports/junit.xml
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml

Jenkins Integration

Add to your Jenkinsfile:

pipeline {
    agent any
    
    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g newman'
            }
        }
        
        stage('API Tests') {
            steps {
                withCredentials([
                    string(credentialsId: 'omise-secret-key', variable: 'SECRET_KEY'),
                    string(credentialsId: 'omise-public-key', variable: 'PUBLIC_KEY')
                ]) {
                    sh '''
                        cat > omise-test-env.json << EOF
{
  "name": "Omise Test",
  "values": [
    {"key": "base_url", "value": "https://api.omise.co"},
    {"key": "secret_key", "value": "${SECRET_KEY}"},
    {"key": "public_key", "value": "${PUBLIC_KEY}"}
  ]
}

Overview​

What is Postman?​

Why Use the Omise Collection?​

Installation​

Prerequisites​

Importing the Collection​

Method 1: Direct Import from URL​

Method 2: Import from File​

Method 3: Fork from Workspace​

Verifying Installation​

Setting Up Environment Variables​

Creating Test Environment​

Creating Production Environment​

Using Environment Variables in Requests​

Selecting Active Environment​

Authentication Configuration​

How Authentication Works​

Configuring Authentication​

Testing Authentication​

Available Endpoints​

Charges​

Customers​

Cards​

Tokens​

Refunds​

Transfers​

Recipients​

Disputes​

Sources​

Balance​

Transactions​

Events​

Webhooks​

Links​

Capabilities​

Chains​

Example Requests​

Creating a Charge​

Creating a Customer​

Creating a Refund​

Creating a Token​

Testing Workflows​

Workflow 1: Complete Payment Flow​

Workflow 2: Customer Management​

Workflow 3: Refund Process​

Workflow 4: 3D Secure Payment​

CI/CD Integration​

Installing Newman​

Exporting Collection and Environment​

Running Tests with Newman​

GitHub Actions Integration​

GitLab CI Integration​

Jenkins Integration​

Overview

What is Postman?

Why Use the Omise Collection?

Installation

Prerequisites

Importing the Collection

Method 1: Direct Import from URL

Method 2: Import from File

Method 3: Fork from Workspace

Verifying Installation

Setting Up Environment Variables

Creating Test Environment

Creating Production Environment

Using Environment Variables in Requests

Selecting Active Environment

Authentication Configuration

How Authentication Works

Configuring Authentication

Testing Authentication

Available Endpoints

Charges

Customers

Cards

Tokens

Refunds

Transfers

Recipients

Disputes

Sources

Balance

Transactions

Events

Webhooks

Links

Capabilities

Chains

Example Requests

Creating a Charge

Creating a Customer

Creating a Refund

Creating a Token

Testing Workflows

Workflow 1: Complete Payment Flow

Workflow 2: Customer Management

Workflow 3: Refund Process

Workflow 4: 3D Secure Payment

CI/CD Integration

Installing Newman

Exporting Collection and Environment

Running Tests with Newman

GitHub Actions Integration

GitLab CI Integration

Jenkins Integration