hipay-professional-sdk
Version:
HiPay Professional SDK for JavaScript
230 lines (229 loc) • 9.23 kB
TypeScript
import { AxiosRequestConfig, AxiosResponse } from 'axios';
import { CancelOrderRequest, CancelOrderResult, CaptureOrderRequest, CaptureOrderResult, CreateOrderRequest, CreateOrderResult, OrderNotificationResult, RefundOrderRequest, RefundOrderResult } from './Types';
import { Omit } from './utils';
export declare class HipayClient {
private static getEndpoint;
private readonly _environment;
private readonly _endpoint;
private readonly _defaultData;
private readonly _defaultReqOpts;
/**
* Create a new HipayClient.
*
* Get your API credentials (login/password) from the dashboard [Toolbox](https://professional.hipay.com/toolbox/).
*
* Important: If you wan't to use the stage environment (for testing) use the sandbox site:
* [test-professional.hipay.com](https://test-professional.hipay.com/toolbox/)!
* Test accounts are validated automatically, just enter random (but valid) information at each step
* (to validate bank information use Bank Name: "HSBC" and IBAN: "FR7630056009271234567890182").
*
* @param opts
*/
constructor(opts: HipayClientOptions);
/**
* Returns client environment
*/
getEnvironment(): Environment;
/**
* Returns client API endpoint
*/
getEndpoint(): string;
private request;
private parseResponse;
/**
* Create a new order.
*
* At the time of payment you must create a new order then redirect the customer to the secure payment page hosted
* by HiPay.
* When the customer makes the payment the order is authorized and you can {@link HipayClient.captureOrder
* capture it}.
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#soap-api-resources-request-a-new-order)
*
* @param req Requests parameters.
* @param opts Requests options (you can set default values when creating the client:
* {@link HipayClientOptions.defaultReqOpts}).
* @return
* - *resolved* with an {@link HipayResponse} when the request complete (with {@link HipayResponse.error
* an error} or {@link HipayResponse.result the result})
* - *rejected* with an {@link HipayException} when an exception occurs (network error, malformed response, ...)
*/
createOrder(req: CreateOrderRequest, opts?: RequestOptions): Promise<HipayResponse<CreateOrderResult>>;
/**
* Capture an order.
*
* Instruct the payment gateway to capture a previously-authorized transaction, i.e. transfer the funds from the
* customer's bank account to the merchant's bank account. This transaction is always preceded by an authorization.
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#soap-api-resources-maintenance-operations)
*
* @param req Requests parameters.
* @param opts Requests options (you can set default values when creating the client:
* {@link HipayClientOptions.defaultReqOpts}).
* @return
* - *resolved* with an {@link HipayResponse} when the request complete (with {@link HipayResponse.error
* an error} or {@link HipayResponse.result the result})
* - *rejected* with an {@link HipayException} when an exception occurs (network error, malformed response, ...)
*/
captureOrder(req: CaptureOrderRequest, opts?: RequestOptions): Promise<HipayResponse<CaptureOrderResult>>;
/**
* Cancel an order.
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#soap-api-resources-maintenance-operations)
*
* @param req Requests parameters.
* @param opts Requests options (you can set default values when creating the client:
* {@link HipayClientOptions.defaultReqOpts}).
* @return
* - *resolved* with an {@link HipayResponse} when the request complete (with {@link HipayResponse.error
* an error} or {@link HipayResponse.result the result})
* - *rejected* with an {@link HipayException} when an exception occurs (network error, malformed response, ...)
*/
cancelOrder(req: CancelOrderRequest, opts?: RequestOptions): Promise<HipayResponse<CancelOrderResult>>;
/**
* Refund an order.
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#soap-api-resources-refund-an-order)
*
* @param req Requests parameters.
* @param opts Requests options (you can set default values when creating the client:
* {@link HipayClientOptions.defaultReqOpts}).
* @return
* - *resolved* with an {@link HipayResponse} when the request complete (with {@link HipayResponse.error
* an error} or {@link HipayResponse.result the result})
* - *rejected* with an {@link HipayException} when an exception occurs (network error, malformed response, ...)
*/
refundOrder(req: RefundOrderRequest, opts?: RequestOptions): Promise<HipayResponse<RefundOrderResult>>;
/**
* Parse Notification (callback) inputs.
*
* After a successful purchase, HiPay calls twice your Notification (callback) URL in background with comprehensive
* information about the payment (the first time for the authorization notification and the second one for the
* capture notification).
* Information are passed through an `xml` field in the body of an http POST request (of type
* `application/x-www-form-urlencoded`).
* This method parses the contents of this xml field and validates the checksum of the request.
*
* Checksum or Signature verification:
* TODO (wait for HiPay support information about documentations errors)
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#server-to-server-notifications-what-is-a-server-to-server-notification)
*
* @param xmlStr The value of the field `xml` (from POST request body)
* @param opts
* @return
* - *resolved* with an {@link HipayNotificationResponse} when no error is encountered
* - *rejected* with an {@link Error} when any error occurs (invalid format, bad signature, ...)
*/
parseNotification(xmlStr: string, opts?: ParseNotificationOptions): Promise<HipayNotificationResponse>;
toString(): string;
}
export interface HipayClientOptions {
/**
* API environment (it defines the endpoint that will be used)
* - `production` set the endpoint to "https://ws.hipay.com/"
* - `stage` set the endpoint to "https://test-ws.hipay.com/"
*
* Note: You can also specify an endpoint URL directly
*/
env: Environment;
/**
* Your API login
*/
login: string;
/**
* Your API password
*/
password: string;
/**
* (not documented by HiPay)
*/
subAccountLogin?: string;
/**
* (not documented by HiPay)
*/
subAccountId?: number;
/**
* Override default requests options.
*
* Default:
* ```typescript
* {
* timeout: 30 * 1000,
* }
* ```
*/
defaultReqOpts?: RequestOptions;
}
export declare type Environment = 'stage' | 'production' | string;
export interface RequestOptions extends Omit<AxiosRequestConfig, 'url' | 'method' | 'baseURL' | 'data' | 'responseType' | 'validateStatus' | 'transformResponse'> {
/**
* The number of milliseconds before the request times out.
*/
timeout: number;
}
interface HipayBaseResponse {
/**
* Reference to the internal axios response.
*/
httpResponse: AxiosResponse;
}
export interface HipaySuccessResponse<T> extends HipayBaseResponse {
/**
* The response result.
*/
result: T;
error: undefined;
}
export interface HipayErrorResponse extends HipayBaseResponse {
/**
* The error.
*/
error: HipayError;
result: undefined;
}
/**
* API response to a request.
*
* If an error has occurred, `error` is defined and `result` is undefined.
* Otherwise, `result` is defined and `error` is undefined.
*/
export declare type HipayResponse<T> = HipaySuccessResponse<T> | HipayErrorResponse;
/**
* API request error.
*
* [HiPay documentation](https://developer.hipay.com/getting-started/platform-hipay-professional/overview/#integration-guidelines-error-handling)
*/
export interface HipayError {
/**
* Error code returned by HiPay.
*/
code: number;
/**
* Error cause description.
*/
description: string;
}
/**
* API request exception.
*
* Unlike {@link HipayError errors}, exceptions are unexpected and unanticipated events (network errors, ...).
*/
export declare class HipayException extends Error {
cause?: Error;
httpResponse?: AxiosResponse;
constructor(message: string, cause: Error, httpResponse?: AxiosResponse);
}
export interface ParseNotificationOptions {
checkMd5Content?: boolean;
checkSignature?: boolean;
}
/**
* @see {@link HipayClient.parseNotification}
*/
export interface HipayNotificationResponse {
mapiversion: string;
md5content: string;
result: OrderNotificationResult;
}
export {};