PayTabs Technical Portal

https://docs.paytabs.com/
Admin
PayTabs Technical Portal offers comprehensive documentation and tools for integrating PayTabs...
Tokens:298,768
Snippets:3,287
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure PaymentSdkConfigBuilder

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-android-sdk/step-2-configure-the-integration-method/configuration-options-and-parameters

Examples showing the builder pattern for required configuration and a comprehensive setup including optional parameters.

```kotlin
val configData = PaymentSdkConfigBuilder(  
    profileId = profileId,  
    serverKey = serverKey,  
    clientKey = clientKey,  
    amount = amount,  
    currencyCode = currency  
)  
    .setMerchantCountryCode(merchantCountryCode)  
    .setCartId(cartId)  
    .setCartDescription(cartDesc)  
    .setBillingData(billingData)      
    .setShippingData(shippingData)  
    .build()
```

```kotlin
val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode)  
    .setCartDescription(cartDesc)  
    .setLanguageCode(locale)  
    .setMerchantIcon(ResourcesCompat.getDrawable(resources, R.drawable.paytabs, null))  
    .setMerchantCountryCode(merchantCountryCode)  
    .setCartId(cartId)  
    .setTransactionClass(transactionClass)  
    .setTransactionType(transType)  
    .setBillingData(billingData)  
    .setShippingData(shippingData)  
    .setCardDiscount(cardDiscount)  
    .setPaymentExpiry(120)  
    .setAlternativePaymentMethods(alternativePaymentMethods)  
    .showBillingInfo(showBillingInfo)  
    .showShippingInfo(showShippingInfo)  
    .forceShippingInfo(forceShippingInfo)  
    .setScreenTitle(screenTitle)  
    .setServerIp("1.1.1.1")  
    .hideCardScanner(false)  
    .setTokenise(tokeniseType, tokenFormat)  
    .isDigitalProduct(isDigitalProduct)  
    .setCardApproval(cardApproval)  
    .linkBillingNameWithCard(true)  
    .build()
```

--------------------------------

### Install PayTabs SDK

Source: https://docs.paytabs.com/manuals/mobile-sdks/react-native-sdk/step-1-setup-and-activate-the-integration-method

Commands to install the PayTabs SDK using NPM or Expo.

```shell
npm install @paytabs/react-native-paytabs@latest --save
```

```shell
expo install @payTabs/react-native-paytabs
```

--------------------------------

### Request Parameter Examples

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Managed-Form/Managed-Form-Step-3-Initiating-Payment/Managed-Form-Initiating-Payment

JSON examples for the mandatory parameters required to initiate a payment request.

```json
{
 "profile_id": 987654
}
```

```json
{
 "tran_type": "sale"
}
```

```json
{
 "tran_class": "ecom"
}
```

```json
{
 "cart_id": "CART#10001"
}
```

```json
{
 "cart_description": "Description of the items/services"
}
```

```json
{
 "cart_currency": "SAR"
}
```

```json
{
 "cart_amount": 500.99
}
```

```json
{
 "customer_details": {
  "name": "first last",
  "email": "email@domain.com",
  "phone": "0522222222",
  "street1": "address street",
  "city": "dubai",
  "state": "du",
  "country": "AE",
  "zip": "12345"
 }
}
```

--------------------------------

### Configure ServerKey

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJs-Configure-the-integration-method

Example of setting the authentication server key.

```javascript
let serverKey = "SJJNZ****D-J2J****ML6-99******DZ",  
  
paytabs.setConfig( profileID, serverKey, region);
```

--------------------------------

### Apply Token Format in Configuration

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-2-configure-the-integration-method/enum

Example of initializing a token format and applying it to the PaymentSdkConfigBuilder.

```kotlin
var tokenFormat = PaymentSdkTokenFormat.AlphaNum32Format()  
  
val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currency)  
.setTokenise(tokeniseType, tokenFormat)  
.build()  
```

--------------------------------

### Profile ID Parameter Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Direct-Payment-Methods/VIBAN-Direct-Payment-Request/VIBAN-Status

Example of the profile_id parameter required for the request.

```json
{
 "profile_id": 987654
}
```

--------------------------------

### Start Card Payment

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-3-initiating-the-payment

Initiate the payment process by passing the configuration to the PaymentManager.

```swift
PaymentManager.startCardPayment(  
  on: self,   
  configuration: configuration,  
  delegate: self  
)  
```

--------------------------------

### Install or Upgrade via CocoaPods

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-1-setup-and-activate-the-integration-method

Add the PayTabsSDK dependency to your Podfile and run the install command to integrate or update the library.

```ruby
pod 'PayTabsSDK', '~> X.X.XX'
```

```bash
pod install
```

--------------------------------

### Configuring Tokenization in PaymentSdkConfigBuilder

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-2-configure-the-integration-method/enum

Example showing how to assign a tokenization type and apply it to the PaymentSdkConfigBuilder.

```kotlin
var tokeniseType = PaymentSdkTokenise.USER_OPTIONAL  
  
val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currency)  
.setTokenise(tokeniseType, tokenFormat)  
.build()  
```

--------------------------------

### Configure ProfileID

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJs-Configure-the-integration-method

Example of setting the merchant Profile ID.

```javascript
let profileID = 8####;  
  
paytabs.setConfig( profileID, serverKey, region);
```

--------------------------------

### Customer Details JSON Sample

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-shipping-and-billing-details

Example JSON structure for the customer_details parameter.

```json
{
 "customer_details": {
  "name": "first last",
  "email": "email@domain.com",
  "phone": "0522222222",
  "street1": "address street",
  "city": "dubai",
  "state": "du",
  "country": "AE",
  "zip": "12345"
 }
}
```

--------------------------------

### Callback URL Configuration

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Request-Response-Parameters/Response-Merchant-Id

Example of including the callback parameter in the initial request payload.

```json
{
    .
    .
    "callback": "https://webhook.site/80XXXX07-ea81-XXXX-b44e-0332XXXXa60b"
    .
    .
}
```

--------------------------------

### Sample createPaymentPage Call

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJS-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-the-payment-page-display-language

A basic example of invoking the createPaymentPage function with all required parameters.

```javascript
PayTabs.createPaymentPage(  
    paymentMethods,  
    transaction_details,  
    cart_details,  
    customer_details,  
    shipping_address,  
    response_URLs,  
    lang,  
    callbackMethod,  
    frameMode  
);
```

--------------------------------

### Full PaymentSDKConfiguration Setup

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-2-configure-the-integration-method/configuration-options-and-parameters?propertyType=optional

Demonstrates the configuration object with all available optional parameters and properties.

```swift
let configuration = PaymentSDKConfiguration(  
    profileID: profileID,  
    serverKey: serverKey,  
    clientKey: clientKey,  
    currency: "SAR",  
    amount: 5.0,  
    merchantCountryCode: "SA"  
)  
.cartID("1234")  
.billingDetails(billingDetails)  
.shippingDetails(shippingDetails)  
.merchantName("Merchant Name")  
.cartDescription("Order #12345 - Electronics Purchase")  
.languageCode("en")  
.tokeniseType(.merchantMandatory)  
.tokenFormat(.hex32)   
.token(nil)  
.transactionreference(nil)  
.merchantIdentifier("merchant.com.yourcompany.app")  
.paymentNetworks([...])  
.simplifyApplePayValidation(true)  
.forceShippingInfo(false)  
.linkBillingNameWithCard(true)  
.showSaveCardsUI(true)  
.requestCVV(true)  
.isDigitalProduct(false)  
.expiryTime(3600)   
.cardDiscounts(nil)  
.cardApproval(cardApproval)  
  
configuration.theme = customTheme  
configuration.transactionType = .sale  
configuration.transactionClass = .ecom  
configuration.screenTitle = "Title"  
configuration.hideCardScanner = false  
configuration.alternativePaymentMethods = [.stcPay, .valu]
```

--------------------------------

### Invoice Redirect URL Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Downloading-Invoice

The redirect URL provided in the API response to guide customers to the payment page.

```json
"redirect_url": "https://secure.paytabs.com/payment/page/59946B********************B4817FD4488"
```

--------------------------------

### Redirect URL Response Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Hosted-Payment-Page/HPP-Step-3-Initiating-Payment/HPP-Initiating-Payment

The JSON response containing the redirect URL required to guide the customer to the payment page.

```json
"redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
```

--------------------------------

### Initialize PaymentSDKConfiguration with All Parameters

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-2-configure-the-integration-method/configuration-options-and-parameters

Comprehensive configuration example including optional settings for tokenization, Apple Pay, and UI customization.

```swift
let configuration = PaymentSDKConfiguration(  
    profileID: profileID,  
    serverKey: serverKey,  
    clientKey: clientKey,  
    currency: "SAR",  
    amount: 5.0,  
    merchantCountryCode: "SA"  
)  
.cartID("1234")  
.billingDetails(billingDetails)  
.shippingDetails(shippingDetails)  
.merchantName("Merchant Name")  
.cartDescription("Order #12345 - Electronics Purchase")  
.languageCode("en")  
.tokeniseType(.merchantMandatory)  
.tokenFormat(.hex32)   
.token(nil)  
.transactionreference(nil)  
.merchantIdentifier("merchant.com.yourcompany.app")  
.paymentNetworks([...])  
.simplifyApplePayValidation(true)  
.forceShippingInfo(false)  
.linkBillingNameWithCard(true)  
.showSaveCardsUI(true)  
.requestCVV(true)  
.isDigitalProduct(false)  
.expiryTime(3600)   
.cardDiscounts(nil)  
.cardApproval(cardApproval)  
  
configuration.theme = customTheme  
configuration.transactionType = .sale  
configuration.transactionClass = .ecom  
configuration.screenTitle = "Title"  
configuration.hideCardScanner = false  
configuration.alternativePaymentMethods = [.stcPay, .valu]  
```

--------------------------------

### Initialize PaymentSdkConfigurationDetails

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-2-configure-the-integration-method/configuration-options-and-parameters

Examples showing the instantiation of configuration details with required parameters versus a full configuration including optional settings.

```dart
 var configuration = PaymentSdkConfigurationDetails(  
        profileId: profileId,  
        serverKey: serverKey,  
        clientKey: clientKey,  
        cartId: cartId,  
        cartDescription: cartDescription,  
        amount: amount,  
        currencyCode: currencyCode,  
        merchantCountryCode: merchantCountryCode  
    );  
```

```dart
var configuration = PaymentSdkConfigurationDetails(  
    profileId: profileId,  
    serverKey: serverKey,  
    clientKey: clientKey,  
    cartId: "cartId,  
    cartDescription: cartDescription,  
    merchantName: "My Store",  
    screentTitle: "Pay Now",  
    amount: 100.0,  
    currencyCode: "SAR",  
    merchantCountryCode: "SA",  
    transactionType: PaymentSdkTransactionType.SALE,  
    transactionClass: PaymentSdkTransactionClass.ECOM,  
  
    billingDetails: billingDetails,  
    shippingDetails: shippingDetails,  
  
    showBillingInfo: true,  
    showShippingInfo: true,  
    forceShippingInfo: false,  
  
    locale: PaymentSdkLocale.EN,  
  );
```

--------------------------------

### GET Invoice Status

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Invoice-status

Retrieve the status of an invoice using a GET request.

```APIDOC
## GET /invoice/status

### Description
Retrieves the status of a specific invoice using the invoice ID.

### Method
GET

### Parameters
#### Query Parameters
- **invoice_id** (INT) - Required - The invoice reference to query.
```

--------------------------------

### Basic PaymentSDKConfiguration Setup

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-2-configure-the-integration-method/configuration-options-and-parameters?propertyType=optional

Initializes the configuration object with mandatory parameters using the builder pattern.

```swift
let configuration = PaymentSDKConfiguration(  
    profileID: profileID,  
    serverKey: serverKey,  
    clientKey: clientKey,  
    currency: "SAR",  
    amount: 5.0,  
    merchantCountryCode: "SA"  
)  
.cartDescription("Flowers")  
.cartID("1234")  
.billingDetails(billingDetails)
```

--------------------------------

### VIBAN Reference Parameter Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Direct-Payment-Methods/VIBAN-Direct-Payment-Request/VIBAN-Status

Example of the VIBAN_ref parameter used to identify the transaction.

```json
{
 "VIBAN_ref": "VB000000020102"
}
```

--------------------------------

### Handling Payment Initiation with Error Catching

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/sending-customized-parameters-user-defined

A complete implementation example showing how to initiate a payment page with custom parameters and handle potential exceptions.

```php
try {  
    $paymentPage = paypage::sendTransaction('sale','ecom')  
      ->sendCart("Order_101", 1000.00, 'Order Description')  
      ->sendUserDefined( [ "udf1"=>"UDF1 Test", "udf2"=>"UDF2 Test", "udf3"=>"UDF3 Test"])  
      ->create_pay_page();  
  
    return $paymentPage;  
  
} catch (\Exception $e) {  
    // Handle errors appropriately  
    return back()->with('error', 'Payment initiation failed: ' . $e->getMessage());  
}
```

--------------------------------

### Void Transaction Payload Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Request-Response-Parameters/Response-Previous-Tran-Ref

Example of a response payload for a void transaction including the previous_tran_ref.

```json
{
    "tran_ref": "TST2430601944067",
    "previous_tran_ref": "TST2430601944066",
    "tran_type": "void",
    "cart_id": "previous_tran_ref code sample Transaction",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "10.00",
    "tran_currency": "SAR",
    "tran_total": "10.00",
    "customer_details": {
        "name": "Technical Support Operations",
        "email": "demo@paytabs.com",
        "street1": "Address",
        "city": "Riyadh",
        "state": "Riyadh",
        "country": "SA",
    },
    "payment_result": {
        "response_status": "A",
        "response_code": "G81709",
        "response_message": "Authorised",
        "transaction_time": "2024-11-01T17:21:49Z"
    },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2025
    },
    "serviceId": 1,
    "profileId": 79010,
    "merchantId": 28882,
    "trace": "PMNT0***.672***2D.00***81F"
}
```

--------------------------------

### Initiating Payment with Tokenization

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-tokenization-sendtokinse

Examples demonstrating how to chain the sendTokinse method within the payment initiation flow.

```php
paypage::sendTransaction('sale','ecom')  
  ->sendCart("Order_101", 1000.00, 'Order Description')  
  ->sendTokinse(true)  
  ->create_pay_page();
```

```php
try {  
    $paymentPage = paypage::sendTransaction('sale','ecom')  
      ->sendCart("Order_101", 1000.00, 'Order Description')  
      ->sendTokinse(true)  
      ->create_pay_page();  
  
    return $paymentPage;  
  
} catch (\Exception $e) {  
    // Handle errors appropriately  
    return back()->with('error', 'Payment initiation failed: ' . $e->getMessage());  
}
```

--------------------------------

### Handling Payment Initiation with sendToken

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-token-based-transactions-sendtoken

A complete example demonstrating how to wrap the payment initiation in a try-catch block to handle potential exceptions.

```php
try {  
    $paymentPage = paypage::sendTransaction('sale','ecom')  
      ->sendCart("Order_101", 1000.00, 'Order Description')  
      ->sendToken("TST2234701408580", "JfN1DVw6w7hrM7mm1P11jNMbzFFAe9WU")  
      ->create_pay_page();  
  
    return $paymentPage;  
  
} catch (\Exception $e) {  
    // Handle errors appropriately  
    return back()->with('error', 'Payment initiation failed: ' . $e->getMessage());  
}
```

--------------------------------

### Install or Upgrade via Carthage

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-1-setup-and-activate-the-integration-method

Specify the repository in your Cartfile and run the update command to fetch the framework.

```text
github "Paytabscom/PayTabs-ios-library-sample" ~> x.x.xx
```

```bash
carthage update
```

--------------------------------

### Invoice ID Parameter Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Retrieve-Invoice-Details

Example of the invoice_id parameter structure used in API requests.

```json
{
   "invoice_id": "10000010001"    
}
```

--------------------------------

### Payment Link Response Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Request-Response-Parameters/Request-Response-cart-currency

Example of a JSON response containing the cart_currency and the payment link URL.

```json
{
    "cart_currency": "SAR",
    .
    .
    "link_url": "https://secure.paytabs.com/payment/link/109430/1474XX7",
    .
    .
}
```

--------------------------------

### Example PayLink URL

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/PayLinks-APIs/PayLinks-Step-3-Initiating-Payment/PayLinks-Payment-Workflow

A concrete example of a PayLink URL used to redirect customers to the payment page.

```text
"https://secure.paytabs.com/payment/page/XXXXXXXXE47EB6D974F412090C176D7BF0B2/start"
```

--------------------------------

### Initialize Payment SDK Configuration

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-2-configure-the-integration-method/configuration-options-and-parameters

Use this configuration object to set up the payment details including profile, keys, and cart information.

```javascript
 var configuration = PaymentSdkConfigurationDetails(  
        profileId: profileId,  
        serverKey: serverKey,  
        clientKey: clientKey,  
        cartId: cartId,  
        cartDescription: cartDescription,  
        amount: amount,  
        currencyCode: currencyCode,  
        merchantCountryCode: merchantCountryCode  
    );  
```

--------------------------------

### Raw Response Data Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Hosted-Payment-Page/HPP-Step-5-handle-the-payment-response/HPP-Step-5-Landing

Example of the raw POST data received from the return URL redirection.

```text
acquirerMessage=&acquirerRRN=&cartId=cart_11111&customerEmail=email%40domain.com&respCode=G84718&respMessage=Authorised&respStatus=A&signature=7a181a32c768621eb6966107752ee70205a01f1c4403a3d13c0ff604f591f988&token=&tranRef=TST2215201242166
```

--------------------------------

### Status Parameter Response Example

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Deposit-and-Payouts/Payouts-Request-Response-Parameters/status-Payouts-Parameter

Example of the status parameter returned within a JSON response object.

```json
{
    "status": "Rejected"
}
```

--------------------------------

### GET Retrieve Invoice Details

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Retrieve-Invoice-Details

Retrieve invoice details using a GET request with the invoice_id as a URL parameter.

```APIDOC
## GET /invoices/{invoice_id}

### Description
Fetch the full invoice details by providing the invoice_id in the URL.

### Method
GET

### Parameters
#### Path Parameters
- **invoice_id** (INT) - Required - The unique identifier for the invoice.
```

--------------------------------

### GET /payment/invoice/{invoice_id}/details

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Retrieve-Invoice-Details

Retrieves invoice details using a GET request with the invoice ID as a path parameter.

```APIDOC
## GET /payment/invoice/{invoice_id}/details

### Description
Retrieves the complete details of a specific invoice using its unique identifier.

### Method
GET

### Endpoint
{{domain}}/payment/invoice/{invoice_id}/details

### Parameters
#### Path Parameters
- **invoice_id** (string) - Required - The unique identifier of the invoice.
```

--------------------------------

### Define Integration Configuration Parameters

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Configure-the-integration-method

Examples of setting required integration keys in the config/PayTabs.php file using environment variables.

```php
return [  
  
    'profile_id' => env('paytabs_profile_id', 100181),  
      
];
```

```php
return [  
  
    'server_key' => env('paytabs_server_key', 'SHJN######-JDR6######-DMMJ######'),  
      
];
```

```php
return [  
  
    'currency' => env('paytabs_currency', 'SAR'),  
      
];
```

```php
return [  
  
    'region' => env('paytabs_region', 'SAU')  
      
];
```

--------------------------------

### Initiate Alternative Payment Method

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-3-initiating-the-payment

Start the payment process by passing the configuration object to the startAlternativePaymentMethod function.

```swift
PaymentManager.startAlternativePaymentMethod(  
  on: self,   
  configuration: configuration,  
  delegate: self  
)
```

--------------------------------

### Install PayTabs Node.js Package

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJs-Step-1-Setup-and-Activate-Integration-Method/NodeJS-Setup-Activate-and-Upgrade-the-integration-method/Install-and-activate

Use this command in your project's command line to install the required PayTabs package.

```bash
npm i paytabs_pt2
```

--------------------------------

### Setting Up Payment Configuration

Source: https://docs.paytabs.com/manuals/mobile-sdks/flutter-bridge/step-3-initiating-the-payment

Initialize the PaymentSdkConfigurationDetails object with merchant credentials and transaction parameters.

```dart
var configuration = PaymentSdkConfigurationDetails(  
        profileId: profileID,  
        serverKey: serverKey,  
        clientKey: clientKey",  
        cartId: cartID,  
        cartDescription: cartDescription,  
        merchantName: merchantName,  
        billingDetails: billingDetails,  
        amount: 0.5,  
        currencyCode: "SAR",  
        merchantCountryCode: "SA");  
```

--------------------------------

### Initialize Payment Configuration

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-3-initiating-the-payment

Create the configuration object with merchant credentials, payment details, and tokenization settings.

```swift
let configuration = PaymentSDKConfiguration(  
  profileID: profileID,  
  serverKey: serverKey,  
  clientKey: clientKey,  
  currency: "SAR",  
  amount: 5.0,  
  merchantCountryCode: "SA")  
  .cartDescription(cartDesc)  
  .cartID(cartId)  
  .billingDetails(billingDetails)  
  
configuration.tokeniseType = .userOptinoal  
configuration.tokenFormat = .hex32  
```

--------------------------------

### SDK Validation Error Example

Source: https://docs.paytabs.com/manuals/mobile-sdks/flutter-bridge/step-4-accepting-the-payment

Example of the callback error object received when a required field like the Cart ID is missing.

```json
{trace: null, code: -1, message: Cart ID is empty!, status: error}
```

--------------------------------

### GET Request Invoice Details Endpoints

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Retrieve-Invoice-Details

Regional endpoints for retrieving invoice details using a GET request with the invoice ID.

```text
https://secure.paytabs.sa/payment/invoice/{invoice_id}/details
```

```text
https://secure.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-egypt.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-oman.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-jordan.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-kuwait.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-iraq.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-morocco.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-doha.paytabs.com/payment/invoice/{invoice_id}/details
```

```text
https://secure-global.paytabs.com/payment/invoice/{invoice_id}/details
```

--------------------------------

### Create PaymentSDKConfiguration Object

Source: https://docs.paytabs.com/manuals/mobile-sdks/native-ios-sdk/step-3-initiating-the-payment

Set up the configuration object with merchant credentials, currency, amount, and billing details.

```swift
let configuration = PaymentSDKConfiguration(  
  profileID: profileID,  
  serverKey: serverKey,  
  clientKey: clientKey,  
  currency: "SAR",  
  amount: 5.0,  
  merchantCountryCode: "SA")  
  .cartDescription(cartDesc)  
  .cartID(cartId)  
  .billingDetails(billingDetails)
```

--------------------------------

### Initiating Payment with URLs

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-the-return-and-callback-urls-sendurls

Example of chaining the sendURLs method within the payment initiation flow.

```php
paypage::sendTransaction('sale','ecom')  
  ->sendCart("Order_101", 1000.00, 'Order Description')  
  ->sendURLs("https://example.com/order-page", "https://api.example.com/callback")  
  ->create_pay_page();
```

```php
try {  
    $paymentPage = paypage::sendTransaction('sale','ecom')  
      ->sendCart("Order_101", 1000.00, 'Order Description')  
      ->sendURLs("https://example.com/order-page", "https://api.example.com/callback")  
      ->create_pay_page();  
  
    return $paymentPage;  
  
} catch (\Exception $e) {  
    // Handle errors appropriately  
    return back()->with('error', 'Payment initiation failed: ' . $e->getMessage());  
}
```

--------------------------------

### Server-Side Validation Error Example

Source: https://docs.paytabs.com/manuals/mobile-sdks/flutter-bridge/step-4-accepting-the-payment

Example of the callback error object received from the PayTabs server when invalid data, such as an incorrect currency code, is provided.

```json
{trace: PMNT0000.68F88000.00004000, code: 206, message: Currency not available, status: error}
```

--------------------------------

### Set Mandatory Configurations

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJS-Step-3-Initiating-the-payment

Configure the SDK with your profile ID, server key, and region before initiating requests.

```javascript
paytabs.setConfig(profileID, serverKey, region)  
```

--------------------------------

### GET Invoice Status Endpoints by Region

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Invoices-APIs/Invoices-Step-7-Manage-Transactions/Invoices-Step-7-Invoice-status

Use these URLs to retrieve invoice status via a GET request. Ensure the correct regional domain is used to avoid authentication issues.

```text
https://secure.paytabs.sa/payment/invoice/{{invoice_id}}/status
```

```text
https://secure.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-egypt.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-oman.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-jordan.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-kuwait.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-iraq.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-morocco.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-doha.paytabs.com/payment/invoice/{{invoice_id}}/status
```

```text
https://secure-global.paytabs.com/payment/invoice/{{invoice_id}}/status
```

--------------------------------

### Initiate Card Payment

Source: https://docs.paytabs.com/manuals/mobile-sdks/react-native-sdk/step-3-initiating-the-payment

Starts the payment process by passing the configuration object to the SDK.

```javascript
RNPaymentSDKLibrary.startCardPayment(JSON.stringify(configuration)).then(result => {  
    if (result["PaymentDetails"] != null) { // Handle transaction details  
        let paymentDetails = result["PaymentDetails"]  
        console.log(paymentDetails)  
    } else if (result["Event"] == "CancelPayment") { // Handle events  
        console.log("Cancel Payment Event")  
    }  
}, function (error) { // Handle error  
    console.log(error)  
});  
```

--------------------------------

### Handling Payment Initiation with Error Catching

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-the-transaction-type-sendtransaction

A robust implementation showing how to initiate a payment page and handle potential exceptions.

```php
try {  
    $paymentPage = paypage::sendTransaction('sale','ecom')  
      ->sendCart("Order_101", 1000.00, 'Order Description')  
      ->create_pay_page();  
  
    return $paymentPage;  
  
} catch (\Exception $e) {  
    // Handle errors appropriately  
    return back()->with('error', 'Payment initiation failed: ' . $e->getMessage());  
}
```

--------------------------------

### 3DS Response Payload

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Request-Response-Parameters/Request-Response-Callback

Example response payload for a 3DS card transaction.

```json
{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500.00",

    "callback": "https://www.{{ yoururl }}.com/{{ yourendpoit }}",

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
        "customer_details": {
        "name": "Demo Account",
        "email": "demo@PayTabs.com",
        "phone": "+966 0000000000",
        "street1": "address street",
        "city": "city",
        "state": "state",
        "country": "SA",
        "zip": "45555",
        "ip": "1.1.1.1"
     },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2022
    },
    "serviceId": 8,

    "serviceId": 2,
    "profileId": 987###,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}
```

```json
{
    "tran_ref": "TST22********159",
    "tran_type": "Sale",
    "cart_id": "CART#1001",
    "cart_description": "Description of the items/services",
    "cart_currency": "SAR",
    "cart_amount": "500.00",

    "callback": "https://www.{{ yoururl }}.com/{{ yourendpoit }}",

    "redirect_url": "https://secure.paytabs.com/payment/page/599458B182E5B6B********************B4817FD44318539688688",
    "customer_details": {
        "name": "Demo Account",
        "email": "demo@PayTabs.com",
        "phone": "+966 0000000000",
        "street1": "address street",
        "city": "city",
        "state": "state",
        "country": "SA",
        "zip": "45555",
        "ip": "1.1.1.1"
     },
    "payment_info": {
        "payment_method": "Visa",
        "card_type": "Credit",
        "card_scheme": "Visa",
        "payment_description": "4111 11## #### 1111",
        "expiryMonth": 12,
        "expiryYear": 2022
    },
    "serviceId": 8,

    "serviceId": 2,
    "profileId": 987###,
    "merchantId": 1*****7,
    "trace": "PMN****4.63****A8.00****C4"
}
```

--------------------------------

### Initialize Payment Configuration

Source: https://docs.paytabs.com/manuals/mobile-sdks/flutter-bridge/step-3-initiating-the-payment

Set up the PaymentSdkConfigurationDetails object with merchant credentials, cart details, and tokenization settings.

```dart
var configuration = PaymentSdkConfigurationDetails(  
        profileId: profileID,  
        serverKey: serverKey,  
        clientKey: clientKey",  
        cartId: cartID,  
        cartDescription: cartDescription,  
        merchantName: merchantName,  
        billingDetails: billingDetails,  
        amount: 0.5,  
        currencyCode: "SAR",  
        merchantCountryCode: "SA");  
  
configuration.tokenFormat = PaymentSdkTokenFormat.AlphaNum20Format;  
configuration.tokeniseType = PaymentSdkTokeniseType.USER_OPTIONAL;  
```

--------------------------------

### Parameter Specification Samples

Source: https://docs.paytabs.com/manuals/PT-API-Endpoints/Integration-Types-Manuals/Request-Response-Parameters/Request-Response-Card-Filter

Examples for configuring the card_filter and card_filter_title parameters.

```text
card_filter
```

```json
{
    "card_filter": "41111,400000,5200000,549838"
}
```

```text
card_filter_title
```

```json
{
    "card_filter_title": "Only accept cards start with 41111,400000"
}
```

--------------------------------

### Initiate Payment Page with sendPaymentCode

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/Laravel/Laravel-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-the-payment-methods-sendpaymentcode

Demonstrates the basic method signature and a full payment initiation flow.

```php
sendPaymentCode(string $code)
```

```php
paypage::sendPaymentCode('all')
  ->sendTransaction('sale','ecom')
  ->sendCart("Order_101", 1000.00, 'Order Description')
  ->create_pay_page();
```

--------------------------------

### Configure Region

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJs-Configure-the-integration-method

Example of setting the merchant account region code.

```javascript
let region = "SAU",  
  
paytabs.setConfig( profileID, serverKey, region);
```

--------------------------------

### Initiate Alternative Payment Method

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-3-initiating-the-payment

Execute the payment process by passing the configuration object to the startAlternativePaymentMethod function.

```javascript
cordova.plugins.CordovaPaymentPlugin.startAlternativePaymentMethod(configuration, function (result) {  
    if (result["status"] == "success") {  
        // Handle transaction details here.  
        var transactionDetails = result["data"];  
    } else if (result["status"] == "error") {  
        // Handle error here the code and message.  
    } else if (result["status"] == "event") {  
        // Handle events here.  
    }  
}, function (error) {  
    console.log(error)  
});  
```

--------------------------------

### Defining the Language Variable

Source: https://docs.paytabs.com/manuals/Backend-Web-Packages/NodeJs/NodeJS-Step-3-Initiating-the-payment/Initiating-The-Payment/manage-the-payment-page-display-language

Example of setting the language variable to English.

```javascript
let lang = "en";
```

--------------------------------

### Initialize PaymentSDKConfiguration

Source: https://docs.paytabs.com/manuals/mobile-sdks/cordova/step-3-initiating-the-payment

Construct the configuration object with merchant credentials, cart details, and tokenization settings.

```javascript
let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();  
configuration.profileID = profileID  
configuration.serverKey = serverKey  
configuration.clientKey = clientKey  
configuration.cartID = cartID  
configuration.currency = "SAR"  
configuration.cartDescription = cartDescription  
configuration.merchantCountryCode = "SA"  
configuration.merchantName = merchantName  
configuration.amount = 0.5  
configuration.billingDetails = billingDetails  
  
configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal  
configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32  
```
Tokens:
Raw