Skip to content

Payment Integration Guide

Overview

This guide provides instructions for integrating the payment processing system with your application. It covers the necessary steps to initiate payments, handle callbacks, and process webhooks.

Prerequisites

Before you begin, ensure that you have:

  1. API credentials with appropriate permissions
  2. Access to the payment gateway test environment
  3. SSL certificates for secure communication
  4. Basic understanding of REST APIs and OAuth2 authentication

Integration Steps

1. Authentication

All API requests must be authenticated using OAuth2 bearer tokens. To obtain a token:

1
2
3
4
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

The response will include an access token that you should include in all subsequent API requests:

1
2
3
4
5
6
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "payment:initiate payment:read"
}

Include the token in the Authorization header of all API requests:

1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. Initiating a Payment

To initiate a payment, send a POST request to the payment initiation endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
POST /payments/initiate
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "bookingNumber": "RES-12345678",
  "hotelId": "10001",
  "guestDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "amount": 150.00,
  "currency": "EUR",
  "description": "Deposit for booking RES-12345678",
  "paymentType": "DEPOSIT",
  "paymentMethod": "CREDIT_CARD",
  "returnUrl": "https://example.com/payment/callback",
  "notificationUrl": "https://example.com/payment/notify"
}

The response will include a payment ID and a redirect URL:

1
2
3
4
5
6
{
  "paymentId": "PAY-98765432",
  "status": "INITIATED",
  "redirectUrl": "https://payment.saferpay.com/vt2/api/Payment/123456789",
  "expiresAt": "2023-07-15T15:30:22Z"
}

3. Redirecting the User

Redirect the user to the redirectUrl to complete the payment. The user will be presented with a payment form where they can enter their payment details.

4. Handling the Callback

After the user completes the payment, they will be redirected to the returnUrl specified in the payment initiation request. The URL will include query parameters with the payment result:

1
https://example.com/payment/callback?paymentId=PAY-98765432&status=COMPLETED

Possible status values: - COMPLETED: Payment was successful - FAILED: Payment failed - CANCELLED: Payment was cancelled by the user

5. Verifying the Payment

To verify the payment status, send a GET request to the payment status endpoint:

1
2
GET /payments/status/PAY-98765432
Authorization: Bearer YOUR_ACCESS_TOKEN

The response will include the current status of the payment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "paymentId": "PAY-98765432",
  "bookingNumber": "RES-12345678",
  "hotelId": "10001",
  "amount": 150.00,
  "currency": "EUR",
  "status": "COMPLETED",
  "paymentMethod": "CREDIT_CARD",
  "transactionId": "TRANS-87654321",
  "transactionDate": "2023-07-15T14:45:30Z"
}

6. Setting Up Webhooks

Webhooks provide asynchronous notifications about payment events. To set up a webhook:

1
2
3
4
5
6
7
8
9
POST /webhooks/register
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "url": "https://example.com/payment/webhook",
  "events": ["payment.completed", "payment.failed", "refund.completed"],
  "secret": "your-webhook-secret"
}

The response will include a webhook ID:

1
2
3
4
5
6
{
  "webhookId": "WH-12345678",
  "url": "https://example.com/payment/webhook",
  "events": ["payment.completed", "payment.failed", "refund.completed"],
  "createdAt": "2023-07-15T10:00:00Z"
}

7. Processing Webhooks

When a payment event occurs, the system will send a POST request to your webhook URL with the event details:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "event": "payment.completed",
  "paymentId": "PAY-98765432",
  "bookingNumber": "RES-12345678",
  "hotelId": "10001",
  "amount": 150.00,
  "currency": "EUR",
  "transactionId": "TRANS-87654321",
  "timestamp": "2023-07-15T14:45:30Z"
}

The request will include a signature in the X-Signature header. You should verify this signature to ensure that the webhook is authentic:

1
X-Signature: sha256=7d38cdd7343548c9f325094b89fc3ed82bc6120c6b0c2c9d2d28e24a0da81a35

To verify the signature:

  1. Concatenate the webhook secret with the request body
  2. Calculate the SHA-256 hash of the concatenated string
  3. Compare the calculated hash with the hash in the X-Signature header
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import hmac
import hashlib

def verify_signature(secret, body, signature):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, signature.replace('sha256=', ''))

Respond with a 200 OK status code to acknowledge receipt of the webhook.

Testing

Test Environment

The payment system provides a sandbox environment for testing payment flows without processing actual payments:

1
https://bookingservice.dev.apps.gustaffo.com/payments

Test Cards

Use the following test cards in the sandbox environment:

Card Type Card Number Expiry Date CVV 3D Secure Password
Visa 4111111111111111 Any future Any password1
Mastercard 5555555555554444 Any future Any password1
Amex 378282246310005 Any future Any password1

Test Scenarios

  1. Successful Payment: Use any of the test cards with a valid expiry date
  2. Failed Payment: Use card number 4111111111111111 with expiry date 01/23
  3. 3D Secure Authentication: Use any test card and enter "password1" when prompted
  4. Cancelled Payment: Close the payment form without completing the payment

Troubleshooting

Common Issues

Authentication Errors

  • Error: "Invalid client credentials"
  • Solution: Check that your client ID and client secret are correct

Payment Initiation Errors

  • Error: "Invalid payment amount"
  • Solution: Ensure that the payment amount is greater than zero

Webhook Verification Errors

  • Error: "Invalid webhook signature"
  • Solution: Check that you are using the correct webhook secret and that the signature calculation is correct

Support

If you encounter any issues not covered in this guide, please contact support at:

  • Email: support@gustaffo.com
  • Phone: +43 1 12345678
  • Support Hours: Monday to Friday, 9:00 AM to 5:00 PM CET

Best Practices

Security

  1. Keep credentials secure: Store client secrets and webhook secrets securely
  2. Use HTTPS: Always use HTTPS for all API requests and webhook endpoints
  3. Verify webhooks: Always verify webhook signatures to prevent unauthorized requests
  4. Limit access: Restrict access to payment-related endpoints to authorized personnel

Error Handling

  1. Implement retries: Retry failed API requests with exponential backoff
  2. Log errors: Log all errors with detailed information for troubleshooting
  3. Handle edge cases: Implement proper error handling for network issues, timeouts, and other edge cases

Performance

  1. Implement caching: Cache payment status and other frequently accessed data
  2. Use asynchronous processing: Process webhooks asynchronously to avoid blocking the main application flow
  3. Monitor performance: Set up monitoring and alerting for payment-related operations

Changelog

Version 1.0.0 (2023-07-01)

  • Initial release of the Payment Integration Guide

Version 1.1.0 (2023-08-15)

  • Added support for PayPal integration
  • Updated test card information
  • Added troubleshooting section

Additional Resources

Back to top