Payment API Reference

The Payment module provides comprehensive payment processing functionality with support for multiple payment providers including Stripe, Klarna, and Vipps.

Overview

The Payment API allows you to:

• Get available payment methods
• Create Stripe payment intents and checkout sessions
• Initialize Klarna payments and retrieve orders
• Process Vipps mobile payments
• Validate payment statuses

import SdkService from '../services/SdkService';

// Access payment methods
const payment = SdkService.sdk.payment;

Methods

getAvailableMethods()

Retrieves all available payment methods for the current channel.

getAvailableMethods(): Promise<GetAvailablePaymentMethodsDto[]>

Example

const paymentMethods = await SdkService.sdk.payment.getAvailableMethods();

paymentMethods.forEach(method => {
 console.log(`Payment Method: ${method.name}`);
 console.log(`Provider: ${method.provider}`);
 console.log(`Supported: ${method.is_active}`);
});

Response

interface GetAvailablePaymentMethodsDto {
 id: string;
 name: string;
 provider: 'STRIPE' | 'KLARNA' | 'VIPPS';
 is_active: boolean;
 configuration: Record<string, any>;
}

---

Stripe Integration

stripeIntent()

Creates a Stripe Payment Intent for secure card processing.

stripeIntent(params: {
 checkout_id: string;
 return_ephemeral_key?: boolean;
}): Promise<PaymentIntentStripeDto>

Parameters

Parameter	Type	Required	Description
checkout_id	string	Yes	The checkout session ID
return_ephemeral_key	boolean	No	Whether to return an ephemeral key for mobile SDKs

Example

const paymentIntent = await SdkService.sdk.payment.stripeIntent({
 checkout_id: 'checkout_123',
 return_ephemeral_key: true
});

console.log('Client Secret:', paymentIntent.client_secret);
console.log('Payment Intent ID:', paymentIntent.id);

// Use with Stripe React Native SDK
import { useStripe } from '@stripe/stripe-react-native';

const { confirmPayment } = useStripe();

const handlePayment = async () => {
 const { error } = await confirmPayment(paymentIntent.client_secret, {
 paymentMethodType: 'Card',
 });
 
 if (error) {
 console.error('Payment failed:', error);
 } else {
 console.log('Payment successful!');
 }
};

Response

interface PaymentIntentStripeDto {
 id: string;
 client_secret: string;
 status: string;
 amount: number;
 currency: string;
 ephemeral_key?: string;
 customer?: string;
}

---

stripeLink()

Creates a Stripe Checkout session for hosted payment page.

stripeLink(params: {
 checkout_id: string;
 success_url: string;
 payment_method: string;
 email: string;
}): Promise<InitPaymentStripeDto>

Parameters

Parameter	Type	Required	Description
checkout_id	string	Yes	The checkout session ID
success_url	string	Yes	URL to redirect after successful payment
payment_method	string	Yes	Payment method identifier (usually 'STRIPE')
email	string	Yes	Customer email address

Example

const stripeSession = await SdkService.sdk.payment.stripeLink({
 checkout_id: 'checkout_123',
 success_url: 'https://myapp.com/success',
 payment_method: 'STRIPE',
 email: 'customer@example.com'
});

// Open in WebView or external browser
import { Linking } from 'react-native';
Linking.openURL(stripeSession.url);

Response

interface InitPaymentStripeDto {
 id: string;
 url: string;
 status: string;
}

---

getStripeIntent()

Retrieves the current status of a Stripe Payment Intent.

getStripeIntent(payment_intent_id: string): Promise<Record<any, string>>

Parameters

Parameter	Type	Required	Description
payment_intent_id	string	Yes	The Stripe Payment Intent ID

Example

const intentStatus = await SdkService.sdk.payment.getStripeIntent(
 'pi_1234567890'
);

console.log('Payment status:', intentStatus.status);
console.log('Amount received:', intentStatus.amount_received);

---

Klarna Integration

klarnaInit()

Initializes a Klarna payment session for "Buy Now, Pay Later" functionality.

klarnaInit(params: {
 checkout_id: string;
 country_code: string;
 href: string;
 email?: string;
}): Promise<InitPaymentKlarnaDto>

Parameters

Parameter	Type	Required	Description
checkout_id	string	Yes	The checkout session ID
country_code	string	Yes	ISO country code (e.g., 'SE', 'NO', 'DK')
href	string	Yes	Return URL after payment completion
email	string	No	Customer email address

Example

const klarnaPayment = await SdkService.sdk.payment.klarnaInit({
 checkout_id: 'checkout_123',
 country_code: 'NO',
 href: 'https://myapp.com/confirmation',
 email: 'customer@example.com'
});

console.log('Klarna Order ID:', klarnaPayment.order_id);
console.log('HTML Snippet:', klarnaPayment.html_snippet);

// Render the Klarna widget in a WebView
import { WebView } from 'react-native-webview';

const KlarnaWebView = () => (
 <WebView
 source={{ html: klarnaPayment.html_snippet }}
 style={{ flex: 1 }}
 />
);

Response

interface InitPaymentKlarnaDto {
 order_id: string;
 html_snippet: string;
 status: string;
}

---

klarnaOrder()

Retrieves detailed information about a Klarna order.

klarnaOrder(order_id: string): Promise<KlarnaOrderDto>

Parameters

Parameter	Type	Required	Description
order_id	string	Yes	The Klarna order ID

Example

const klarnaOrder = await SdkService.sdk.payment.klarnaOrder(
 'klarna_order_123'
);

console.log('Order status:', klarnaOrder.status);
console.log('Order amount:', klarnaOrder.order_amount);
console.log('Customer email:', klarnaOrder.billing_address.email);

Response

interface KlarnaOrderDto {
 order_id: string;
 status: string;
 purchase_country: string;
 purchase_currency: string;
 locale: string;
 billing_address: {
 given_name: string;
 family_name: string;
 email: string;
 street_address: string;
 postal_code: string;
 city: string;
 phone: string;
 country: string;
 };
 shipping_address: {
 given_name: string;
 family_name: string;
 email: string;
 street_address: string;
 postal_code: string;
 city: string;
 phone: string;
 country: string;
 };
 order_amount: number;
 order_tax_amount: number;
 order_lines: Array<{
 type: string;
 name: string;
 quantity: number;
 unit_price: number;
 tax_rate: number;
 total_amount: number;
 total_discount_amount: number;
 total_tax_amount: number;
 }>;
 html_snippet: string;
 started_at: string;
 last_modified_at: string;
}

---

Vipps Integration

vippsInit()

Initializes a Vipps mobile payment session (Norwegian mobile payments).

vippsInit(
 checkout_id: string,
 email: string,
 return_url: string
): Promise<{ payment_url: string }>

Parameters

Parameter	Type	Required	Description
checkout_id	string	Yes	The checkout session ID
email	string	Yes	Customer email address
return_url	string	Yes	URL to redirect after payment

Example

const vippsPayment = await SdkService.sdk.payment.vippsInit(
 'checkout_123',
 'customer@example.com',
 'https://myapp.com/success'
);

// Open Vipps app or web interface
import { Linking } from 'react-native';
Linking.openURL(vippsPayment.payment_url);

---

validateVippsPayment()

Validates and retrieves the status of a Vipps payment.

validateVippsPayment(checkout_id: string): Promise<VippsPaymentStatusDto>

Parameters

Parameter	Type	Required	Description
checkout_id	string	Yes	The checkout session ID

Example

const vippsStatus = await SdkService.sdk.payment.validateVippsPayment(
 'checkout_123'
);

console.log('Payment state:', vippsStatus.state);
console.log('Amount authorized:', vippsStatus.aggregate.authorizedAmount);
console.log('PSP Reference:', vippsStatus.pspReference);

Response

interface VippsPaymentStatusDto {
 aggregate: {
 authorizedAmount: { currency: string; value: number };
 cancelledAmount: { currency: string; value: number };
 capturedAmount: { currency: string; value: number };
 refundedAmount: { currency: string; value: number };
 };
 amount: { currency: string; value: number };
 state: 'AUTHORIZED' | 'CAPTURED' | 'CANCELLED' | 'FAILED';
 paymentMethod: {
 type: string;
 cardBin?: string;
 };
 pspReference: string;
 redirectUrl: string;
 reference: string;
 metadata: {
 checkoutId: string;
 channelUserId: string;
 userId: string;
 };
}

Complete Payment Flow Examples

Stripe Card Payment Flow

import React, { useState } from 'react';
import { View, Button, Alert } from 'react-native';
import { useStripe } from '@stripe/stripe-react-native';
import SdkService from '../services/SdkService';

export const StripePaymentFlow: React.FC<{ checkoutId: string }> = ({ checkoutId }) => {
 const { confirmPayment } = useStripe();
 const [loading, setLoading] = useState(false);

 const handleStripePayment = async () => {
 try {
 setLoading(true);
 
 // 1. Create payment intent
 const paymentIntent = await SdkService.sdk.payment.stripeIntent({
 checkout_id: checkoutId,
 return_ephemeral_key: true,
 });

 // 2. Confirm payment with Stripe
 const { error } = await confirmPayment(paymentIntent.client_secret, {
 paymentMethodType: 'Card',
 paymentMethodData: {
 billingDetails: {
 email: 'customer@example.com',
 },
 },
 });

 if (error) {
 Alert.alert('Payment Failed', error.message);
 } else {
 // 3. Verify payment status
 const status = await SdkService.sdk.payment.getStripeIntent(
 paymentIntent.id
 );
 
 if (status.status === 'succeeded') {
 Alert.alert('Success', 'Payment completed successfully!');
 }
 }
 } catch (error) {
 console.error('Payment error:', error);
 Alert.alert('Error', 'Payment processing failed');
 } finally {
 setLoading(false);
 }
 };

 return (
 <Button
 title={loading ? "Processing..." : "Pay with Card"}
 onPress={handleStripePayment}
 disabled={loading}
 />
 );
};

Klarna Payment Flow

import React, { useState } from 'react';
import { View, Button, Modal } from 'react-native';
import { WebView } from 'react-native-webview';
import SdkService from '../services/SdkService';

export const KlarnaPaymentFlow: React.FC<{ checkoutId: string }> = ({ checkoutId }) => {
 const [klarnaHtml, setKlarnaHtml] = useState<string | null>(null);
 const [showModal, setShowModal] = useState(false);

 const handleKlarnaPayment = async () => {
 try {
 const klarnaPayment = await SdkService.sdk.payment.klarnaInit({
 checkout_id: checkoutId,
 country_code: 'NO',
 href: 'https://myapp.com/confirmation',
 email: 'customer@example.com',
 });

 setKlarnaHtml(klarnaPayment.html_snippet);
 setShowModal(true);
 } catch (error) {
 console.error('Klarna init error:', error);
 }
 };

 return (
 <>
 <Button
 title="Pay with Klarna"
 onPress={handleKlarnaPayment}
 />
 
 <Modal visible={showModal} animationType="slide">
 <View style={{ flex: 1 }}>
 {klarnaHtml && (
 <WebView
 source={{ html: klarnaHtml }}
 onNavigationStateChange={(navState) => {
 if (navState.url.includes('confirmation')) {
 setShowModal(false);
 // Handle payment completion
 }
 }}
 />
 )}
 <Button
 title="Close"
 onPress={() => setShowModal(false)}
 />
 </View>
 </Modal>
 </>
 );
};

Error Handling

Payment operations can fail for various reasons. Always implement proper error handling:

const handlePaymentError = (error: any) => {
 if (error.code === 'PAYMENT_DECLINED') {
 Alert.alert('Payment Declined', 'Your payment method was declined. Please try another card.');
 } else if (error.code === 'INSUFFICIENT_FUNDS') {
 Alert.alert('Insufficient Funds', 'Your account has insufficient funds for this transaction.');
 } else if (error.networkError) {
 Alert.alert('Network Error', 'Please check your internet connection and try again.');
 } else {
 Alert.alert('Payment Error', 'An unexpected error occurred. Please try again.');
 }
};

Best Practices

1. Security

• Never store payment credentials in your app
• Always use secure HTTPS endpoints
• Validate payments server-side

2. User Experience

• Show loading states during payment processing
• Provide clear error messages
• Allow users to retry failed payments

3. Testing

// Use test mode for development
const isTestMode = __DEV__;
const testCheckoutId = 'test_checkout_123';

if (isTestMode) {
 // Use test payment methods
 console.log('Using test payment environment');
}

Related APIs

• Checkout API - Create checkout sessions
• Cart API - Manage shopping carts
• Market API - Get available payment methods by region (coming soon)