0
# Payment Service
1

2
Interface for payment service implementations providing methods for creating, authorizing, capturing, and refunding payments through various payment gateways.
3

4
**Deprecation Notice**: Use `AbstractPaymentProcessor` from @medusajs/medusa instead.
5

6
## Capabilities
7

8
### Static Methods
9

10
Type checking and identification methods for payment services.
11

12
```javascript { .api }
13
/**
14
 * Static property identifying this as a payment service
15
 */
16
static _isPaymentService: boolean;
17

18
/**
19
 * Checks if an object is a payment service
20
 * @param {object} obj - Object to check
21
 * @returns {boolean} True if obj is a payment service
22
 */
23
static isPaymentService(obj: object): boolean;
24
```
25

26
### Service Identification
27

28
Method to get the service identifier.
29

30
```javascript { .api }
31
/**
32
 * Returns the service identifier from constructor
33
 * @returns {string} Service identifier
34
 */
35
getIdentifier(): string;
36
```
37

38
**Usage Example:**
39

40
```javascript
41
import { PaymentService } from "medusa-interfaces";
42

43
class StripePaymentService extends PaymentService {
44
  static identifier = "stripe";
45
  
46
  getIdentifier() {
47
    return this.constructor.identifier; // Returns "stripe"
48
  }
49
}
50
```
51

52
### Core Payment Operations
53

54
Abstract methods that must be implemented by child classes.
55

56
```javascript { .api }
57
/**
58
 * Creates a payment to be processed with the service's payment gateway
59
 * @param {object} cart - The cart that the payment should cover
60
 * @returns {Promise<object>} Promise resolving to payment data
61
 * @throws {Error} If not overridden by child class
62
 */
63
createPayment(cart: object): Promise<object>;
64

65
/**
66
 * Retrieves an existing payment for a cart
67
 * @param {object} cart - The cart whose payment should be retrieved
68
 * @returns {Promise<object>} Promise resolving to payment object as stored with provider
69
 * @throws {Error} If not overridden by child class
70
 */
71
retrievePayment(cart: object): Promise<object>;
72

73
/**
74
 * Updates a payment when the cart is updated
75
 * @param {object} cart - The cart whose payment should be updated
76
 * @returns {Promise<object>} Promise resolving to updated payment object
77
 * @throws {Error} If not overridden by child class
78
 */
79
updatePayment(cart: object): Promise<object>;
80

81
/**
82
 * Gets the status of a payment
83
 * @returns {any} Payment status
84
 * @throws {Error} If not overridden by child class
85
 */
86
getStatus(): any;
87

88
/**
89
 * Authorizes a payment for later capture
90
 * @returns {any} Authorization result
91
 * @throws {Error} If not overridden by child class
92
 */
93
authorizePayment(): any;
94

95
/**
96
 * Captures a previously authorized payment
97
 * @returns {any} Capture result
98
 * @throws {Error} If not overridden by child class
99
 */
100
capturePayment(): any;
101

102
/**
103
 * Processes a refund for a payment
104
 * @returns {any} Refund result
105
 * @throws {Error} If not overridden by child class
106
 */
107
refundPayment(): any;
108

109
/**
110
 * Deletes a payment
111
 * @returns {any} Deletion result
112
 * @throws {Error} If not overridden by child class
113
 */
114
deletePayment(): any;
115
```
116

117
### Optional Methods
118

119
Methods with default implementations that can be overridden.
120

121
```javascript { .api }
122
/**
123
 * Retrieves saved payment methods for a customer
124
 * @param {object} customer - Customer object
125
 * @returns {Promise<array>} Promise resolving to array of saved payment methods
126
 */
127
retrieveSavedMethods(customer: object): Promise<array>;
128
```
129

130
## Implementation Example
131

132
```javascript
133
import { PaymentService } from "medusa-interfaces";
134

135
class CustomPaymentService extends PaymentService {
136
  static identifier = "custom-payment";
137
  
138
  constructor(options) {
139
    super();
140
    this.options_ = options;
141
  }
142

143
  async createPayment(cart) {
144
    // Create payment with external provider
145
    const paymentData = await this.externalProvider.createPayment({
146
      amount: cart.total,
147
      currency: cart.region.currency_code,
148
      customer: cart.customer_id
149
    });
150
    
151
    return {
152
      id: paymentData.id,
153
      status: "pending",
154
      data: paymentData
155
    };
156
  }
157

158
  async authorizePayment(paymentData) {
159
    // Authorize payment with external provider
160
    const result = await this.externalProvider.authorize(paymentData.id);
161
    
162
    return {
163
      status: result.status,
164
      data: result
165
    };
166
  }
167

168
  async capturePayment(paymentData) {
169
    // Capture authorized payment
170
    const result = await this.externalProvider.capture(paymentData.id);
171
    
172
    return {
173
      status: result.status,
174
      data: result
175
    };
176
  }
177

178
  async refundPayment(paymentData, refundAmount) {
179
    // Process refund
180
    const result = await this.externalProvider.refund(
181
      paymentData.id, 
182
      refundAmount
183
    );
184
    
185
    return {
186
      status: result.status,
187
      data: result
188
    };
189
  }
190

191
  async retrievePayment(cart) {
192
    // Retrieve existing payment
193
    return await this.externalProvider.getPayment(cart.payment_id);
194
  }
195

196
  async updatePayment(cart) {
197
    // Update payment details
198
    return await this.externalProvider.updatePayment(cart.payment_id, {
199
      amount: cart.total
200
    });
201
  }
202

203
  getStatus(paymentData) {
204
    return paymentData.status;
205
  }
206

207
  async deletePayment(paymentData) {
208
    // Delete payment
209
    return await this.externalProvider.deletePayment(paymentData.id);
210
  }
211

212
  async retrieveSavedMethods(customer) {
213
    // Retrieve customer's saved payment methods
214
    return await this.externalProvider.getSavedMethods(customer.id);
215
  }
216
}
217
```
218

219
## Error Handling
220

221
All abstract methods throw descriptive errors when not implemented:
222

223
- `"createPayment must be overridden by the child class"`
224
- `"getPayment must be overridden by the child class"`  
225
- `"updatePayment must be overridden by the child class"`
226
- `"getStatus must be overridden by the child class"`
227
- `"authorizePayment must be overridden by the child class"`
228
- `"capturePayment must be overridden by the child class"`
229
- `"refundPayment must be overridden by the child class"`
230
- `"deletePayment must be overridden by the child class"`