PayShipGo Logo

PayShipGo API Documentation

Developer's Guide

Welcome to the PayShipGo API documentation. Here, you'll find all the necessary information to integrate our payment and shipping services into your platform. We are committed to providing a simple and streamlined experience for developers. This page provides a full overview of our API, along with code examples to get started.

Before diving in, we invite you to explore our detailed guides and references to facilitate the integration process and ensure all queries are addressed. Let's build something amazing together!

PayShipGo Payment API Documentation

All API requests require authentication using your Merchant ID and API Key. Include these in the request headers:

{
  "X-Merchant-ID": "your_merchant_id",
  "X-API-Key": "your_api_key",
  "Content-Type": "application/json"
}

Base URL: https://api.payshipgo.com/v1

POST

Create Payment Session

Creates a new payment session for processing a transaction.

Request Body:

{
  "amount": 1000.00,
  "currency": "PHP",
  "gateway": "pesopay", // Options: pesopay, dragonpay, paypal, gcash
  "payment_method": "card", // Varies by gateway
  "order_id": "ORDER123",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+639123456789"
  },
  "billing_address": {
    "street": "123 Main St",
    "city": "Makati",
    "state": "Metro Manila",
    "postal_code": "1234",
    "country": "PH"
  },
  "success_url": "https://yourstore.com/success",
  "cancel_url": "https://yourstore.com/cancel"
}

Endpoint: /payment/session

Response:

{
  "status": "success",
  "session_id": "sess_123456789",
  "payment_url": "https://checkout.payshipgo.com/sess_123456789",
  "expires_at": "2024-01-14T15:30:00Z"
}
GET

Check Payment Status

Retrieves the current status of a payment session.

Endpoint: /payment/session/{session_id}/status

Response:

{
  "status": "completed", // pending, completed, failed, cancelled
  "payment_id": "pay_123456789",
  "amount": 1000.00,
  "currency": "PHP",
  "payment_method": "card",
  "gateway": "pesopay",
  "timestamp": "2024-01-14T15:30:00Z"
}
POST

Process Refund

Initiates a refund for a completed payment.

Request Body:

{
  "payment_id": "pay_123456789",
  "amount": 1000.00, // Optional, if partial refund
  "reason": "Customer request",
  "reference_id": "REF123"
}

Endpoint: /payment/refund

Response:

{
  "status": "success",
  "refund_id": "ref_123456789",
  "amount": 1000.00,
  "currency": "PHP",
  "payment_id": "pay_123456789",
  "timestamp": "2024-01-14T15:30:00Z"
}
POST

Create Recurring Payment

Sets up a recurring payment schedule.

Request Body:

{
  "customer_id": "cust_123456789",
  "amount": 1000.00,
  "currency": "PHP",
  "gateway": "pesopay",
  "interval": "month", // day, week, month, year
  "interval_count": 1,
  "start_date": "2024-02-01",
  "end_date": "2024-12-31", // Optional
  "payment_method": {
    "type": "card",
    "token": "tok_123456789" // Obtained from initial payment
  }
}

Endpoint: /payment/recurring

Response:

{
  "status": "success",
  "subscription_id": "sub_123456789",
  "next_payment_date": "2024-02-01",
  "schedule": {
    "interval": "month",
    "interval_count": 1,
    "start_date": "2024-02-01",
    "end_date": "2024-12-31"
  }
}
POST

Generate Invoice

Creates a new invoice for payment collection.

Request Body:

{
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+639123456789"
  },
  "items": [
    {
      "description": "Product A",
      "quantity": 2,
      "unit_price": 500.00
    }
  ],
  "due_date": "2024-01-21",
  "currency": "PHP",
  "notes": "Payment for January order"
}

Endpoint: /payment/invoice

Response:

{
  "status": "success",
  "invoice_id": "inv_123456789",
  "amount": 1000.00,
  "currency": "PHP",
  "payment_url": "https://invoice.payshipgo.com/inv_123456789",
  "due_date": "2024-01-21",
  "created_at": "2024-01-14T15:30:00Z"
}
POST

Webhook Configuration

Register webhook endpoints for payment notifications.

Request Body:

{
  "url": "https://yourstore.com/webhooks/payment",
  "events": [
    "payment.success",
    "payment.failed",
    "refund.processed",
    "subscription.renewed"
  ],
  "description": "Payment notifications endpoint"
}

Endpoint: /payment/webhooks

Response:

{
  "status": "success",
  "webhook_id": "whk_123456789",
  "secret_key": "whsec_123456789", // Use this to verify webhook signatures
  "events": [
    "payment.success",
    "payment.failed",
    "refund.processed",
    "subscription.renewed"
  ]
}

Webhook Events

PayShipGo sends webhook notifications for various payment events. Here's an example webhook payload:

{
  "id": "evt_123456789",
  "type": "payment.success",
  "created": "2024-01-14T15:30:00Z",
  "data": {
    "payment_id": "pay_123456789",
    "amount": 1000.00,
    "currency": "PHP",
    "status": "completed",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    }
  }
}

Error Handling

All API errors follow this format:

{
  "status": "error",
  "code": "invalid_request",
  "message": "The provided payment method is not supported",
  "request_id": "req_123456789"
}

Common error codes:

  • `invalid_request`: Missing or invalid parameters
  • `authentication_failed`: Invalid credentials
  • `insufficient_funds`: Payment failed due to insufficient funds
  • `gateway_error`: Payment gateway technical error
  • `rate_limit_exceeded`: Too many requests

PayShipGo Shipping API Documentation

All shipping API requests require the same authentication headers as the payment API:

{
  "X-Merchant-ID": "your_merchant_id",
  "X-API-Key": "your_api_key",
  "Content-Type": "application/json"
}

Base URL: https://api.payshipgo.com/v1

POST

Calculate Shipping Rates

Get shipping rates from available carriers based on package details.

Request Body:

{
  "origin": {
    "address": "123 Sender St",
    "city": "Makati",
    "state": "Metro Manila",
    "postal_code": "1234",
    "country": "PH",
    "contact_number": "+639123456789"
  },
  "destination": {
    "address": "456 Receiver St",
    "city": "Cebu",
    "state": "Cebu",
    "postal_code": "6000",
    "country": "PH",
    "contact_number": "+639987654321"
  },
  "package": {
    "weight": 1.5, // in kg
    "dimensions": {
      "length": 30, // in cm
      "width": 20,
      "height": 10
    },
    "declared_value": 1000.00
  },
  "service_preferences": {
    "carriers": ["lbc", "jnt", "2go", "flash"], // Optional: specific carriers
    "delivery_speed": "standard" // standard, express, same_day
  }
}

Endpoint: /shipping/rates

Response:

{
  "status": "success",
  "rates": [
    {
      "carrier": "lbc",
      "service_name": "Express",
      "amount": 150.00,
      "currency": "PHP",
      "estimated_days": 2,
      "guaranteed_delivery": false
    },
    {
      "carrier": "flash",
      "service_name": "Same Day",
      "amount": 250.00,
      "currency": "PHP",
      "estimated_days": 0,
      "guaranteed_delivery": true,
      "cutoff_time": "15:00:00"
    }
  ]
}
POST

Create Shipment

Create a new shipment with your chosen carrier.

Request Body:

{
  "rate_id": "rate_123456789", // From rates response
  "sender": {
    "name": "John Doe",
    "address": "123 Sender St",
    "city": "Makati",
    "state": "Metro Manila",
    "postal_code": "1234",
    "country": "PH",
    "contact_number": "+639123456789",
    "email": "sender@example.com"
  },
  "recipient": {
    "name": "Jane Smith",
    "address": "456 Receiver St",
    "city": "Cebu",
    "state": "Cebu",
    "postal_code": "6000",
    "country": "PH",
    "contact_number": "+639987654321",
    "email": "recipient@example.com"
  },
  "package": {
    "weight": 1.5,
    "dimensions": {
      "length": 30,
      "width": 20,
      "height": 10
    },
    "declared_value": 1000.00,
    "description": "Electronics",
    "items": [
      {
        "description": "Smartphone",
        "quantity": 1,
        "value": 1000.00
      }
    ]
  },
  "service_options": {
    "insurance": true,
    "signature_required": true,
    "cash_on_delivery": {
      "amount": 1000.00,
      "currency": "PHP"
    }
  },
  "reference": "ORDER123"
}

Endpoint: /shipping/shipments

Response:

{
  "status": "success",
  "shipment_id": "ship_123456789",
  "tracking_number": "TRACK123456789",
  "label_url": "https://api.payshipgo.com/v1/shipping/labels/ship_123456789",
  "carrier": "lbc",
  "service": "Express",
  "estimated_delivery": "2024-01-16",
  "pickup_schedule": {
    "date": "2024-01-14",
    "window": "13:00-17:00"
  }
}
GET

Get Shipment Details

Retrieve details of an existing shipment.

Endpoint: /shipping/shipments/{shipment_id}

Response:

{
  "status": "success",
  "shipment_id": "ship_123456789",
  "tracking_number": "TRACK123456789",
  "carrier": "lbc",
  "service": "Express",
  "current_status": "in_transit",
  "status_detail": "Package in sorting facility",
  "estimated_delivery": "2024-01-16",
  "tracking_history": [
    {
      "status": "picked_up",
      "location": "Makati City",
      "timestamp": "2024-01-14T13:30:00Z",
      "description": "Package picked up from sender"
    },
    {
      "status": "in_transit",
      "location": "Makati Sorting Facility",
      "timestamp": "2024-01-14T15:30:00Z",
      "description": "Package in sorting facility"
    }
  ]
}
POST

Schedule Pickup

Schedule a pickup for one or more shipments.

Request Body:

{
  "pickup_date": "2024-01-15",
  "preferred_time_window": "13:00-17:00",
  "location": {
    "address": "123 Sender St",
    "city": "Makati",
    "state": "Metro Manila",
    "postal_code": "1234",
    "country": "PH",
    "contact_name": "John Doe",
    "contact_number": "+639123456789"
  },
  "shipments": ["ship_123456789", "ship_987654321"],
  "special_instructions": "Please call before arrival"
}

Endpoint: /shipping/pickups

Response:

{
  "status": "success",
  "pickup_id": "pick_123456789",
  "confirmation_number": "PCK123456789",
  "scheduled_date": "2024-01-15",
  "time_window": "13:00-17:00",
  "carrier": "lbc"
}
POST

Address Validation

Validate an address before creating a shipment.

Request Body:

{
  "address": "123 Test St",
  "city": "Makati",
  "state": "Metro Manila",
  "postal_code": "1234",
  "country": "PH"
}

Endpoint: /shipping/validate-address

Response:

{
  "status": "success",
  "is_valid": true,
  "normalized_address": {
    "address": "123 Test Street",
    "city": "Makati City",
    "state": "Metro Manila",
    "postal_code": "1234",
    "country": "PH"
  },
  "service_coverage": {
    "lbc": true,
    "jnt": true,
    "2go": true,
    "flash": true
  }
}
GET

Generate Shipping Label

Generate or retrieve a shipping label for a shipment.

Endpoint: /shipping/labels/{shipment_id}

Query Parameters:
- `format`: pdf (default) or zpl - `size`: 4x6 (default) or A4

Response:

{
  "status": "success",
  "label_url": "https://api.payshipgo.com/v1/shipping/labels/ship_123456789.pdf",
  "expires_at": "2024-01-15T15:30:00Z"
}
DELETE

Cancel Shipment

Cancel a shipment that hasn't been picked up.

Endpoint: /shipping/shipments/{shipment_id}

Response:

{
  "status": "success",
  "shipment_id": "ship_123456789",
  "cancellation_id": "can_123456789",
  "refund_amount": 150.00,
  "currency": "PHP"
}

Webhook Events

PayShipGo sends webhook notifications for various shipping events. Configure these in the webhook settings.

{
  "id":  "evt_123456789",
  "type": "shipment.status_update",
  "created": "2024-01-14T15:30:00Z",
  "data": {
    "shipment_id": "ship_123456789",
    "tracking_number": "TRACK123456789",
    "status": "delivered",
    "location": "Cebu City",
    "timestamp": "2024-01-14T15:30:00Z",
    "details": "Package delivered to recipient"
  }
}

Error Handling

All API errors follow this format:

{
  "status": "error",
  "code": "invalid_address",
  "message": "The provided delivery address is invalid or unsupported",
  "request_id": "req_123456789"
}

Common error codes:

  • `invalid_address`: Address validation failed
  • `service_unavailable`: Carrier service not available for route
  • `package_overweight`: Package exceeds carrier weight limits
  • `pickup_unavailable`: Pickup service not available at location
  • `rate_calculation_failed`: Unable to calculate shipping rates
  • `shipment_already_cancelled`: Shipment cannot be cancelled

Code Examples

const axios = require('axios');

const PAYSHIPGO_BASE_URL = 'https://api.payshipgo.com/v1';
const config = {
  headers: {
    'X-Merchant-ID': 'your_merchant_id',
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  }
};

// Payment Examples
async function paymentExamples() {
  // POST: Create Payment Session
  try {
    const paymentSession = await axios.post(`${PAYSHIPGO_BASE_URL}/payment/session`, {
      amount: 1000.00,
      currency: "PHP",
      gateway: "pesopay",
      payment_method: "card",
      order_id: "ORDER123",
      customer: {
        email: "customer@example.com",
        name: "John Doe",
        phone: "+639123456789"
      }
    }, config);
    console.log('Payment Session:', paymentSession.data);
  } catch (error) {
    console.error('Error creating payment:', error.response.data);
  }

  // GET: Check Payment Status
  try {
    const paymentStatus = await axios.get(
      `${PAYSHIPGO_BASE_URL}/payment/session/sess_123456789/status`,
      config
    );
    console.log('Payment Status:', paymentStatus.data);
  } catch (error) {
    console.error('Error checking status:', error.response.data);
  }

    // DELETE: Cancel Payment
    try {
      const cancelPayment = await axios.delete(
        `${PAYSHIPGO_BASE_URL}/payment/session/sess_123456789`,
        config
      );
      console.log('Payment Cancelled:', cancelPayment.data);
    } catch (error) {
      console.error('Error cancelling payment:', error.response.data);
    }
}

// Shipping Examples
async function shippingExamples() {
  // POST: Create Shipment
  try {
    const shipment = await axios.post(`${PAYSHIPGO_BASE_URL}/shipping/shipments`, {
      rate_id: "rate_123456789",
      sender: {
        name: "John Doe",
        address: "123 Sender St",
        city: "Makati",
        state: "Metro Manila",
        postal_code": "1234",
        country: "PH",
        contact_number": "+639123456789"
      },
      recipient: {
        name: "Jane Smith",
        address: "456 Receiver St",
        city: "Cebu",
        state: "Cebu",
        postal_code": "6000",
        country: "PH",
        contact_number": "+639987654321"
      },
      package: {
        weight: 1.5,
        dimensions: {
          length: 30,
          width: 20,
          height: 10
        }
      }
    }, config);
    console.log('Shipment Created:', shipment.data);
  } catch (error) {
    console.error('Error creating shipment:', error.response.data);
  }

  // GET: Track Shipment
  try {
    const tracking = await axios.get(
      `${PAYSHIPGO_BASE_URL}/shipping/shipments/ship_123456789`,
      config
    );
    console.log('Tracking Info:', tracking.data);
  } catch (error) {
    console.error('Error tracking shipment:', error.response.data);
  }

  // DELETE: Cancel Shipment
    try {
      const cancelShipment = await axios.delete(
        `${PAYSHIPGO_BASE_URL}/shipping/shipments/ship_123456789`,
        config
      );
      console.log('Shipment Cancelled:', cancelShipment.data);
    } catch (error) {
      console.error('Error cancelling shipment:', error.response.data);
    }
}

Frequently Asked Questions (FAQs)

How long does it take to integrate PayShipGo into my e-commerce platform?

Integration typically takes 2-5 business days, depending on your platform and requirements. We provide comprehensive documentation, SDKs, and support to streamline the process.

What payment methods are supported by PayShipGo?

PayShipGo supports multiple payment methods including credit/debit cards, online banking, e-wallets (GCash, PayMaya, Coins.ph), over-the-counter payments, and cryptocurrency through our integrated payment gateways (PesoPay, Dragonpay, PayPal, and GCash).

How do refunds work with PayShipGo?

Refunds can be processed through our API or dashboard. Full or partial refunds are supported and typically process within 5-7 business days, depending on the payment method and gateway used.

What shipping carriers are available through PayShipGo?

We partner with major Philippine carriers including LBC Express, J&T Express, 2GO Express, and Flash Express, offering nationwide coverage and various shipping options.

How does real-time tracking work?

PayShipGo provides real-time tracking through our API and webhook notifications. Updates are synchronized with carrier tracking systems and can be integrated into your platform or forwarded to customers via email/SMS.

What are the security measures in place for payments?

PayShipGo implements PCI-DSS compliant security measures, encryption for data transmission, tokenization for sensitive information, and fraud detection systems. We also support 3D Secure authentication for card payments.

How does Cash on Delivery (COD) work with PayShipGo?

COD is supported through our integrated carriers. Funds are typically remitted to merchants within 3-5 business days after successful delivery, with real-time notifications for collection status.

What happens if a shipment is lost or damaged?

All shipments include basic insurance coverage. Claims can be filed through our platform, and we handle coordination with carriers. Additional insurance coverage is available for high-value items.

Can I customize shipping rates for my customers?

Yes, PayShipGo allows merchants to set custom shipping rates, add handling fees, and create rule-based pricing based on weight, destination, or other factors.

How do international shipments work?

International shipping is available through 2GO Express, with coverage in over 220 countries. We handle customs documentation and provide international tracking support.

What are the transaction fees for using PayShipGo?

Transaction fees vary by payment method and volume. Standard rates are 2.9% + PHP 15 for card payments, 2.5% for e-wallets, and custom rates for high-volume merchants. Shipping fees are based on carrier rates with volume discounts available.

How do I handle failed payments or delivery attempts?

Failed payments trigger automatic notifications and retry options. Failed deliveries are automatically rescheduled, with options for recipient coordination through our platform.

Can I integrate PayShipGo with my existing e-commerce platform?

Yes, we provide plugins for popular platforms like Shopify, WooCommerce, and Magento, plus a comprehensive API for custom integrations.

How do webhooks work for real-time updates?

Webhooks provide real-time notifications for payment and shipping events. You can configure endpoint URLs and select specific events to monitor through our dashboard or API.

What kind of support does PayShipGo provide?

We offer technical documentation, API support, and a responsive customer support team via email, live chat, and phone for onboarding and issue resolution.

;